Kin
A graph-native code repository for people and AI agents.
Open source Open in the app JSON README (API)
About
A graph-native code repository for people and AI agents.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- ai.kinlab
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.7.2
- Stars
- 47
- Forks
- 5
- Open pull requests
- 9
- Last push
- 2026-09-07T20:11:19Z
- Repository state
- ativo
- Language
- Rust
- License
- Apache-2.0
- Added
- 2026-08-29 03:00:12
- Updated
- 2026-09-11 08:04:16
- Origin id
ai.kinlab/kin
README
<p align="center">
<img src="docs/assets/kin-banner-2026.png" alt="Kin, the system of record for AI-written software" width="100%" />
</p>
<div align="center">
<h3>The diff is not the change.</h3>
<p><strong>The system of record for AI-written software.</strong></p>
[](LICENSE) [](https://github.com/firelock-ai/kin/releases/latest) [](https://kinlab.ai)
</div>
AI writes a change in seconds. Working out what it touches has not gotten any
faster.
Every agent reads a repository the way a person would. Search, open files,
follow callers, build the picture, throw it away when the session ends. The
next one starts over. The reviewer starts over again. Most AI tools rebuild
context for each task. Kin keeps a durable semantic record across tasks,
agents, and changes.
Git shows which lines changed. Kin shows what the change affects.
Kin makes the graph the repository. Entities, relationships, exact source, and
change history are what you commit, branch, and merge, and files stay a
projection so ordinary tools keep working.
Agents stop rebuilding context and start editing code. Reviewers see what a
change touches before it merges.
Kin is a public alpha. It runs today as a local CLI, a daemon, an MCP server for
agents, a review surface, and a graph-backed filesystem projection. It is
pre-1.0, so expect rough edges and breaking changes. See the
[latest stable release](https://github.com/firelock-ai/kin/releases/latest) and
[what is real today and what is alpha](#what-is-real-today-and-what-is-alpha) before
you put it in a critical workflow.
Point it at a repository you know and ask it something you already know the
answer to. Or watch it run on Kin's own repositories at
[kinlab.ai/demo](https://kinlab.ai/demo).
## See it on a real repository
A one-line signature change in ripgrep looks harmless in the diff. Ask
`kin impact` about it, before any compiler runs, and it names what the edit
reaches. The callers of the changed signature come first, then everything
those callers pull in behind them.
<p align="center">
<img src="docs/assets/kin-impact-ripgrep.png" alt="kin impact on ripgrep: a one-line signature edit, and Kin surfaces the entities it affects before a compiler runs" width="100%" />
</p>
Recorded against a prepared graph at ripgrep commit
`e89fff89ac9af12e8d4ce9d5fd07beb408ca730f`. A one-line signature edit, and Kin
surfaces the entities it affects before a compiler runs. The graph was built
beforehand. No compiler ran. The two commands are the ones in the quickstart
below: `kin init .` to build the graph, then `kin impact` on the entity you
changed.
The raw run directory for this capture is not public yet, so treat it as a
recipe you can re-run rather than a trace you can audit.
Kin surfaces what the change touches. Whether the change is correct stays with
your compiler, tests, and review. The graph is built beforehand by `kin init`,
and building it is the expensive part; after that, impact questions are
answered from graph truth, not from re-reading the tree.
## Quickstart
Install, admit your repository, check the graph, ask it something. Wire your
agent last. The agent tools answer from the graph, so a client pointed at a
repository with no graph gets a tool surface with nothing behind it.
Run the installer on its own and finish any setup prompts:
```sh
curl -fsSL https://get.kinlab.dev/install | sh
```
Once it finishes, reload your shell with this separate command:
```sh
exec "$SHELL" -l
```
At the new prompt, replace the path below with your repository's location and
run this block:
```sh
cd /path/to/your/repository &&
kin init . &&
kin overview
```
`kin overview` prints what the graph now holds: entity counts by kind, by
language, and the files carrying the most of them. If it prints counts, the
graph is real and the commands below have something to answer from.
The rest of this section is the same path with the detail behind each step.
### 1. Install Kin
On macOS or Linux, run the installer on its own and finish any setup prompts:
```sh
curl -fsSL https://get.kinlab.dev/install | sh
```
Once it finishes, reload your shell with this separate command:
```sh
exec "$SHELL" -l
```
The installer resolves the [latest stable release](https://github.com/firelock-ai/kin/releases/latest),
verifies its published SHA-256 checksum, installs the managed binaries under
`~/.kin`, and launches setup. Running the explicit `agent` intent, which
[step 5](#5-wire-your-agent) does once the graph exists, configures the built-in
MCP server for detected supported clients. Use `--intent local` for CLI and
filesystem use without MCP configuration, or `--intent editor` for the VS Code
path.
npm, Homebrew, and a manual archive resolve that same public release channel:
```sh
npm install -g @kinlab/kin@latest
brew install firelock-ai/kin/kin
```
Each archive and its `.sha256` file is published under
`https://github.com/firelock-ai/kin/releases/latest/download/`, and the release
page lists the asset names.
Confirm what you installed with `kin --version`, whichever path you took.
[The quickstart doc](docs/quickstart.md#1-install) carries the operator detail:
the asset matrix, what to do when a global npm install hits `EACCES`, how the
Homebrew formula is regenerated from each release rather than hand-maintained,
and `kin setup uninstall` when you want the integrations gone.
On Windows, run `irm https://get.kinlab.dev/install.ps1 | iex` in PowerShell.
Native Windows x86_64 support is early. Repository admission works: `kin init` imports a Git repository and publishes graph authority, and graph, lexical, and daemon-backed queries answer natively. Transparent filesystem projection is not shipped on Windows, and the end-to-end install proof does not yet cover MCP or review workflows there, so WSL2 remains the recommended path for the full Kin experience.
Read [Platform and maturity](#platform-and-maturity) below before choosing a
Windows install path.
### 2. Admit your repository as graph truth
Replace the path below with your repository's location:
```sh
cd /path/to/your/repository && kin init .
```
In a detected Git repository, `kin init` atomically admits complete reachable
history, refs, raw objects, the exact workspace tree, and admission policy into
repository-v6 graph authority. A worktree with uncommitted edits, staged
changes, or untracked files still admits: `kin init` admits the committed state
and discloses what it did not admit. It never substitutes an exact-HEAD snapshot or
raw-filesystem semantic rebuild. Supported repository-local remote URLs,
refspecs, branch tracking, and push defaults are sealed into Kin's Git
coexistence configuration; unsafe, ambiguous, or unsupported transfer settings
fail closed before publication.
Admission also derives the semantic entity and relation layer for every
supported entity-source file in that history, and `kin init` reports the durable,
generation-bound counts it committed. `kin status` reports that repository
authority view; `kin graph status` separately reports the daemon's mutable live
query graph, which may include later derived enrichment.
Query surfaces consume graph-owned enrichment when it exists and report its
absence instead of hiding the gap behind raw file search.
`kin init` is the slow step and the one that earns the rest. It admits your Git
history into the graph, and every answer after it comes from that graph rather
than from re-reading the tree. Measured on a fresh Debian 12 container with 4
CPUs and 8 GiB against the release npm serves today, the installer took 4
seconds, `kin init` took 139 seconds on a 503-file repository with 1,983
commits, and the first `kin locate` answered in 6.7 seconds while the daemon
cold-started, then in 71 milliseconds warm. Those are separately measured legs
of one sitting, not one timed run, and a repository with deeper history takes
longer.
#### Which files become entities
"Supported entity-source file" means a file one of Kin's language adapters
claims. The adapter registry is the whole set, and every file in a repository
resolves through it:
| Language | 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` |
A `.h` header is read as C++ when its contents say so, so a C++ project does not
lose namespaces and templates to the C grammar.
Everything else is admitted as content and stays queryable as history and text,
but is not parsed into entities and relations. That includes Markdown, HTML and
CSS, SQL, YAML, JSON and TOML, shell scripts, Objective-C, Scala, Elixir, Dart,
Lua, R, Zig, Haskell, and Nix. If your language is on that list, `locate` and
`refs` will not find symbols in it.
### 3. Check the graph is ready
```sh
kin graph status
kin embed
```
`kin graph status` reports the daemon's live query graph and its coverage.
Admission derives the semantic entities, not their vectors, so run `kin embed`
to add local vector similarity over them and confirm coverage with
`kin graph status` again.
One thing to expect on a small repository: `kin init` starts a background
download of the roughly 523 MB embedding model, and a conversion that finishes
in seconds can beat it. When that happens the first `kin locate` ranks on
lexical and graph signals alone and says why on the line beneath its rows. If
that line reports the model still downloading, run the query again once it
lands. If it reports that none of it arrived, do not wait on it: `kin embed`
fetches the rest.
### 4. Ask it something you already know the answer to
This is the honest way to judge it. Pick a helper you know the callers of, or a
subsystem you could describe from memory, and see whether Kin agrees with you.
A question about code you've never read tells you nothing about whether the
answer is right.
```sh
kin locate "<something you already know is in this repository>"
kin refs ExactEntityName
kin trace ExactEntityName
kin impact ExactEntityName
```
Replace `ExactEntityName` with a symbol returned by `locate`. `locate` finds the
entities relevant to an intent, `refs` shows graph-owned callers/importers and
references, and `trace` returns the focal entity plus nearby semantic context.
Once embeddings are complete, your configured AI agent can use the vector-backed
`semantic_locate` tool; `get_context_pack`, `find_references`, and
`trace_data_flow` expose the graph neighborhood directly.
`impact` walks the other way from `refs` and shows what sits downstream of the
entity you are about to change. Replace the `locate` string with a behavior you
could already point to in the source.
### 5. Wire your agent
Now that the graph exists, point your agent at it:
```sh
kin setup --intent agent
```
Use `kin setup --intent editor` for the VS Code path, or `--intent local` for
CLI and filesystem use with no MCP configuration. Confirm the resulting
machine-readable health checklist with `kin setup status --json`.
[Works with your agent](#works-with-your-agent) has the per-client one-liners
and the standard MCP entry.
## Why I built this
I work with coding agents a lot, and the same thing kept bothering me. Before an
agent can change anything, it spends a stretch of its run working out where
things live and how they connect. Then the next session does that work again.
Meanwhile I'm doing a version of it myself, trying to piece together enough of
the same picture to review what it actually did. You're paying a tax to
re-understand what was already understood.
At some point I started wondering why that structural understanding isn't just
part of the repository.
Git is a great content tracker. Linus said it himself when he made it: it's a
stupid content tracker. It only tracks what changed. Kin records the software.
Everybody is trying to put bolt-ons on top of Git, and I understand why. My
thesis is that it's the wrong way to store code for the velocity and the way
we're doing coding in 2026.
It's like using a paper map versus Google Maps. Same roads either way. One of
them knows where you are and what connects to what.
I've been working on this for six months in my spare time, which has not been
much spare time. I've got a substantial alpha built. I've taken it as far as I
can on my own, and I'm ready to let this thing shine. It's just engineering work
from here on.
## What is real today, and what is alpha
Real today. The graph is the repository. Kin has its own commits, branches, and
merges, with Git import and export beside them. The exact source is preserved
byte for byte. The CLI, the bundled MCP server, and the VS Code extension all
answer from that same graph. Local repository work runs on your machine.
These are the limits worth knowing before you start.
**Admission holds every commit's tree at once.** `kin init` materializes one
resolved tree per commit and keeps every one of them, so what a conversion needs
follows history depth multiplied by tree size. On a history too long for the
machine, Kin refuses in words with a memory forecast, before it captures
anything, rather than dying partway. Commits multiplied by tracked files is the
number that decides it. Measured against the release npm serves today, refusal
starts somewhere above 6.44 million on a 16 GB machine and 12.88 million on
32 GB. `redis/hiredis`, 1,390 commits over 79 files, admits in under three
minutes and leaves a 310 MB store. `axios`, 2,180 commits over 466 files, admits
in about seven minutes. `facebook/react` is 21,679 commits over 7,213 tracked
files, which is 156 million, and a normal clone of it is refused. A shallow
clone is not the way around it: `git clone --depth` leaves a boundary Kin
refuses, because a
history whose oldest commits have absent parents cannot be captured losslessly.
There is no partial-history mode.
**Some repositories refuse to import at all.** Repositories carrying submodules
or Git LFS are refused before admission. Kin does not model submodules yet, so
refusing is the correct answer rather than a silent partial import.
**Git export names Kin as the author's mailbox.** `kin git export` writes native
Kin commits with the author's name and `kin@localhost` as the email, and no
sign-off trailer. Commits that came in from Git are reused as their original
objects, so their identity is untouched.
**`kin init` adds exactly one ignore rule.** It writes `/.kin/` into
`.git/info/exclude`, which is local to your checkout, and leaves your tracked
`.gitignore` alone. Whether a teammate's checkout carries a Kin store is their
business, not a tracked file's.
**Not every language becomes entities.** The adapter table in
[step 2](#which-files-become-entities) is the whole set. Everything else is
admitted as content and stays queryable as history and text, but `locate` and
`refs` will not find symbols in it.
**The graph can still miss relationships.** Coverage is real and it is not
complete, so treat an empty answer as a question rather than as a proof. You
still need your compiler, your tests, and your own judgment.
**No format change ships without a migration path.** No release will drop an
existing store without a tested migration path. A repository admitted from Git
can always be re-admitted from Git. State that exists only in Kin will be
carried forward by an upgrade command shipped with any format change, or the
format change does not ship. A format change never rewrites your working tree.
What that recovery looks like, measured on a 261-commit repository: delete
`.kin`, run `kin init` again, and everything Git holds comes back, all 61 refs
byte-identical. Nothing native comes back. A commit, a branch, a review, and a
spec that existed only in Kin were gone, while the edited file survived as an
uncommitted working-tree change. Re-admission also mints a new repository id
unless you pass `--adopt-repository-id`. That is the gap the upgrade command
above exists to close.
[Platform and maturity](#platform-and-maturity) below has the per-platform
boundaries, the memory floors, and what a green release does and does not
establish.
## The stack
Kin is one system with a few clear public surfaces:
| Surface | What it does |
| --- | --- |
| **[kin](https://github.com/firelock-ai/kin)** | Semantic system of record: CLI, daemon, graph lifecycle, MCP, review, provenance, and Git coexistence. |
| **[kin-vfs](https://github.com/firelock-ai/kin-vfs)** | Projects graph-owned files through normal filesystem calls so existing tools can keep using files. |
| **[kin-editor](https://github.com/firelock-ai/kin-editor)** | VS Code access to the entity explorer, semantic search, trace, review, and rename surfaces. |
| **[Kin MCP](docs/mcp-tools.md)** | Typed graph tools for AI agents, bundled into `kin` and launched with `kin mcp start`. |
| **[KinLab](https://kinlab.ai)** | Hosted collaboration and control plane. Public repository connection is not a first-run flow yet. |
## How the pieces fit
Kin is the system of record for AI-written software, and everything in the map
below either reaches that authority or supports it. Humans and AI agents come in
through the CLI, the bundled MCP server, or the VS Code extension. All
three ask the same daemon, and the daemon answers from graph authority rather
than by re-reading the tree. `kin-vfs` projects that same graph back through
ordinary filesystem calls, so editors, compilers, and build systems keep seeing
files. Git sits beside the graph as an import and export boundary rather than as
an answer path, and KinLab is the hosted layer over the same authority.
```mermaid
flowchart TD
people["Humans and AI agents"]
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
```
Underneath those surfaces are the layers the system is built from:
| Layer | Role |
| --- | --- |
| **[kin-db](https://github.com/firelock-ai/kin-db)** | Graph storage, snapshots, indexing, text search, and vector search. |
| **[kin-model](https://github.com/firelock-ai/kin-model)** | Canonical types and domain models shared across the stack. |
| **[kin-blobs](https://github.com/firelock-ai/kin-blobs)** | Content-addressable blob storage. |
| **[kin-search](https://github.com/firelock-ai/kin-search)** | Lexical search primitives and staged retrieval. |
| **[kin-vector](https://github.com/firelock-ai/kin-vector)** | Vector and nearest-neighbor substrate. |
| **[kin-infer](https://github.com/firelock-ai/kin-infer)** | Inference and embedding substrate. |
| **[kin-lsp](https://github.com/firelock-ai/kin-lsp)** | Language-server enrichment feeding the semantic layer. |
These are implementation layers of one system, not separate products a new user
needs to assemble. None of them is installed separately.
## Open source and the Kin ecosystem
The core of Kin is open source under 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),
and [kin-editor](https://github.com/firelock-ai/kin-editor), plus the supporting
libraries kin-model, kin-blobs, kin-search, kin-vector, kin-infer, kin-lsp, and
kin-actions.
[KinLab](https://kinlab.ai) is a proprietary product built on this open core: the
hosted collaboration and control-plane layer described above.
The same boundary applies to how benchmark work is shared. The [benchmark
specification and a standalone, dependency-free bundle verifier](https://github.com/firelock-ai/kin-bench-spec)
are public, so a merge-trust benchmark claim can be checked without access to the
runner that produced it. The runner and proof infrastructure that produce sealed evidence bundles (the
orchestration, the pinned-release proof gate, and the hosted measurement
environment) remain private for now. The spec and verifier open first; the runner
can open later.
## Version control without Git
Kin keeps a full change history with no Git underneath it. In an empty
directory with no `.git`, the same binary records changes, branches, merges,
and history, and Git never runs. This is that loop, with the output it printed
on one real run of a build of `main`. `kin init`, `kin status`, and `kin diff`
say more than is shown here; the lines below are theirs, unedited, with the
rest trimmed.
Start an empty repository and record a first change:
```sh
mkdir kin-demo && cd kin-demo
kin init
```
```
Authority: repository-v6 (graph-owned)
Default ref: refs/heads/main
History: unborn (no synthetic commit)
Workspace: empty exact tree
Store size: 17.4 KiB under .kin/ (no Git object store here to compare against)
```
```sh
cat > retry.py <<'PY'
def backoff(attempt):
return min(2 ** attempt, 30)
PY
kin commit -m "Add the retry backoff"
```
```
starting the kin daemon for this repository; the first query after a start waits for it to load the graph
kin daemon ready in 1.8s
Created semantic change f635b52070f2944aa1c8651fec50cfa62e1cc21c00760137f62f971a7c27642f on branch 'refs/heads/main' (2 entities, 0 relations, 1 artifacts)
Recorded in Kin authority, not in git. `git status` stays dirty until you run `kin eject` or push this branch to a Kin remote.
```
The first commit starts the repository's daemon. Before that, right after
`kin init`, `kin status` reports durable authority alone and says so on its
`Tree:` line; once the daemon is up, every `kin status` measures the working
copy. Who made the change comes from your Git identity when you have one, and
otherwise from `default_author` in `.kin/config.toml`. Kin refuses to record a
change attributed to nobody.
Branch, change the function on the branch, and commit there:
```sh
kin branch create cap-backoff
kin branch switch cap-backoff
```
```
Created refs/heads/cap-backoff at change f635b52070f2944aa1c8651fec50cfa62e1cc21c00760137f62f971a7c27642f (authority generation 3)
Switched to refs/heads/cap-backoff at change f635b52070f2944aa1c8651fec50cfa62e1cc21c00760137f62f971a7c27642f (1 projected entries, authority generation 4)
```
```sh
cat > retry.py <<'PY'
def backoff(attempt):
"""Exponential backoff, capped at a minute."""
return min(2 ** attempt, 60)
PY
kin status
```
```
Kin repository-v6 status
Head: symbolic refs/heads/cap-backoff
Tree: 198609d9406becdd1fb97f1f3d16d8d869dc382c38823f2b88aa75f72d927029 (1 artifacts, ahead of its base change as admitted 0s ago)
Refs: 2, default refs/heads/main
Durable semantic enrichment: present (2 entities, 0 relations, 1 changes at authority generation 5, workspace generation 3; completion not attested)
Untracked host content: none, measured 0s ago
```
```sh
kin commit -m "Raise the backoff cap to a minute"
```
```
Created semantic change 64cce9085641a7eee86bd2b870567ac524835e2e80488f7e5444f7cf9b42c065 on branch 'refs/heads/cap-backoff' (2 entities, 0 relations, 1 artifacts)
```
Back on `main`, record a second change so the merge has two real parents, then
merge the branch:
```sh
kin branch switch main
cat > retry_test.py <<'PY'
from retry import backoff
def test_first_attempt_waits_one_second():
assert backoff(0) == 1
PY
kin commit -m "Add a first backoff test"
kin merge cap-backoff
```
```
Switched to refs/heads/main at change f635b52070f2944aa1c8651fec50cfa62e1cc21c00760137f62f971a7c27642f (1 projected entries, authority generation 7)
Created semantic change 18abd82f3a295696fa4938fc078613c0abe4a3214dd6ec0eb81f8a7c1f747105 on branch 'refs/heads/main' (2 entities, 3 relations, 1 artifacts)
Merged refs/heads/cap-backoff into refs/heads/main as change 4137af4647e6b838771d5e4ce98d8a604304b9d0a66fdb4e0931e828d6b75c9c (2 projected entries, authority generation 9)
```
The merge composed both sides by entity identity against their common base,
with no line-level text merge, and published one change carrying both parents.
`kin log` walks that history and `kin diff` shows what the merge brought in,
as artifacts, as entities, and as lines:
```sh
kin log
```
```
change 4137af4647e6b838771d5e4ce98d8a604304b9d0a66fdb4e0931e828d6b75c9c
Author: Kin Demo <demo@example.com>
Date: 2026-09-05T01:15:32.635348+00:00
Origin: native
Parents: 18abd82f3a295696fa4938fc078613c0abe4a3214dd6ec0eb81f8a7c1f747105 64cce9085641a7eee86bd2b870567ac524835e2e80488f7e5444f7cf9b42c065
Deltas: entities=2 relations=0 tree=1 policy=false
Merge refs/heads/cap-backoff into refs/heads/main
change 18abd82f3a295696fa4938fc078613c0abe4a3214dd6ec0eb81f8a7c1f747105
Author: Kin Demo <demo@example.com>
Date: 2026-09-05T01:15:32.339226+00:00
Origin: native
Parents: f635b52070f2944aa1c8651fec50cfa62e1cc21c00760137f62f971a7c27642f
Deltas: entities=2 relations=3 tree=1 policy=false
Add a first backoff test
change 64cce9085641a7eee86bd2b870567ac524835e2e80488f7e5444f7cf9b42c065
Author: Kin Demo <demo@example.com>
Date: 2026-09-05T01:15:31.791709+00:00
Origin: native
Parents: f635b52070f2944aa1c8651fec50cfa62e1cc21c00760137f62f971a7c27642f
Deltas: entities=2 relations=0 tree=1 policy=false
Raise the backoff cap to a minute
change f635b52070f2944aa1c8651fec50cfa62e1cc21c00760137f62f971a7c27642f
Author: Kin Demo <demo@example.com>
Date: 2026-09-05T01:15:30.609174+00:00
Origin: native
Deltas: entities=2 relations=0 tree=1 policy=true
Add the retry backoff
```
```sh
kin diff HEAD~1 HEAD
```
```
Kin repository-v6 diff
Base: HEAD~1 (e5aa80af2498ad1d8f8c5a756f24467773a7f12c46039395deb691a0e09ff0bc)
Head: HEAD 4137af4647e6b838771d5e4ce98d8a604304b9d0a66fdb4e0931e828d6b75c9c (f86d6f68558a54372da1c08cedd8549dd98733110e3f2db6193dc8314ba10c11)
Artifacts: +0 ~1 -0
Entities: +0 ~2 -0
Relations: +0 ~0 -0
M retry.py -> retry.py [aab37f62-f986-4543-8187-4af2b8984e0a] blob 0ceda974a82e648bf6e6d40efccc9489eb4b73fa5ab3f0c5cfd35df4911cd524 mode=100644 -> blob c0b44cec88f49e73cc31f7f439ec1b10d9d73cfe1c414dc539106886d4747cce mode=100644
E~ 0a69467a-63d6-5c34-ac35-632cefde30b7 retry -> retry
E~ 6cd876cf-cc8a-50bd-94be-e0a2fde3208d backoff -> backoff
@@ -1,2 +1,3 @@
def backoff(attempt):
- return min(2 ** attempt, 30)
+ """Exponential backoff, capped at a minute."""
+ return min(2 ** attempt, 60)
```
`HEAD~1` is the merge's first parent, the test commit, so the diff is exactly
what `cap-backoff` contributed: one artifact, the two entities in it (the
module and the function), and the lines. `kin checkout`, `kin stash`,
`kin rollback`, `kin blame`, and `kin conflicts` with `kin resolve` round out
the set, and `kin capabilities` prints where each one stands.
[The CLI reference](docs/cli-reference.md#branches-merges-and-exact-trees) has
every flag.
Sharing a native repository between machines is still in progress, and public
repository connection through KinLab is not a first-run flow yet. What the
transfer commands do today: `kin clone` takes a KinLab locator or the HTTP
endpoint of another machine's running Kin daemon, adopts that repository's
identity into a fresh local workspace, and remembers the origin it came from.
`kin push` sends your new changes to that saved origin one verified pack at a
time, and refuses rather than forces when the remote has moved past you.
`kin pull` admits what the origin has that you do not and moves your working
tree onto it, and when uncommitted work stops the tree from following, it says
so and keeps the history it received. Each of the three is exercised between two
Kin daemons over HTTP by the test suite.
## Works with your agent
Kin ships its own agent, and it's the path I recommend for agent work. `kin
agent run` drives any OpenAI-compatible endpoint, so a local model in LM Studio,
Ollama, llama.cpp or vLLM works from the same flags as a hosted one, and it
reaches the graph over the same MCP server every other client uses.
```sh
kin agent run --task "Find where the retry backoff is computed and document it" \
--model qwen/qwen3.6-35b-a3b --base-url http://localhost:1234/v1
```
What makes it different from pointing another agent at the MCP server is that the
rule is enforced inside the agent rather than borrowed from a vendor's permission
layer. It has Kin's tools plus exactly two local ones, `edit_file` and
`write_file`. There is no shell, no grep and no file-reading tool, so it cannot
answer a repository question from raw file search, and a tool it invents is
refused by name. When Kin reports that an empty result cannot be trusted, the
agent is told the answer is unknown and given the named gap instead of concluding
the thing does not exist. Every edit runs inside a Kin transaction under a Kin
session, so the change carries provenance naming the agent. Run `kin agent doctor
--base-url <url>` first to check both halves answer. See
[the CLI reference](docs/cli-reference.md#kin-agent) for the full surface.
Working with Claude Code, Codex, Cursor, Gemini and anything else that speaks MCP
stays first class. `kin setup --intent agent` configures every client it detects
in one pass. These are the per-client one-liners when you would rather install Kin
directly.
Run `kin init .` in the repository before you wire a client, not after. These
tools answer from the graph, so a client pointed at a directory with no graph
gets a tool surface with nothing behind it. `kin setup` says so itself: its
round-trip check reports "no initialized Kin repository at or above" the
directory it ran in, and tells you to run `kin init` there and re-run setup.
Claude Code, from inside a session:
```
/plugin marketplace add firelock-ai/kin
/plugin install kin@kin
```
Codex:
```sh
codex plugin marketplace add firelock-ai/kin
codex plugin add kin@kin
```
Gemini CLI:
```sh
gemini extensions install https://github.com/firelock-ai/kin
```
Cursor takes a one-click install link. Paste this into Cursor or into your
browser's address bar:
```
cursor://anysphere.cursor-deeplink/mcp/install?name=kin&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBraW5sYWIva2luIiwibWNwIiwic3RhcnQiXX0=
```
Kiro takes the same thing as a web link:
[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 takes the standard entry below rather than a one-liner. Its CLI reads
`~/.cline/mcp.json`. In the VS Code extension, open the MCP Servers panel, then
the Configure tab, then Configure MCP Servers, and add the entry there.
Every other client that reads a standard MCP config takes this entry:
```json
{
"mcpServers": {
"kin": { "command": "npx", "args": ["-y", "@kinlab/kin", "mcp", "start"] }
}
}
```
`kin setup status` and `kin doctor` recognize this exact shape, alongside the
absolute-path form `kin setup` writes, and grade anything else MISCONFIGURED. Do
not shorten `command` to a bare `kin`, because agent clients do not reliably
inherit your shell `PATH`. `@kinlab/kin-mcp` is the older launcher and keeps
working for configurations that already name it; new ones should point at
`@kinlab/kin`, which ships the same MCP server as one mode of the full CLI.
The wrapper needs Node 20 or newer, and on its first run it downloads the
matching Kin release, verifies its published SHA-256, and caches the binaries per
user. Codex CLI wants the same thing as TOML under `[mcp_servers.kin]`.
One caveat worth repeating: these tools answer from the graph, so the repository
has to be admitted with `kin init .` and embedded with `kin embed` before
`semantic_locate` can rank anything. [llms-install.md](llms-install.md) is that
whole path written so an agent can follow it unattended, from a bare machine to a
first verified tool call.
## Review an AI-written change
**AI writes code. Kin proves what changed.**
Run `kin init` on the branch you want to review so the relevant Git history is in
the graph, then pass explicit commit SHAs to the report-only shadow gate:
```sh
kin review shadow "$(git rev-parse main)..$(git rev-parse HEAD)"
```
The result is `PASS`, `NEEDS ATTENTION`, or `WOULD BLOCK`, and it comes with the
impact Kin derived from the graph, the context needed to repair it, and the
evidence behind both. Authorship is declared, not verified. The command will not
block your merge or change graph state. It hands evidence to a human or a CI
policy and stops there.
## How Kin relates to Git
Beside Git today. Repository authority over time. During brownfield adoption,
Git remains an explicit import/export interoperability boundary; it never
answers Kin runtime queries or repairs missing graph truth.
- `kin init` imports complete reachable Git history and exact parent edges.
Kin deliberately has no partial-history or snapshot-only initialization mode.
- After import, Kin's graph owns repository identity, tree state, history, refs,
and semantic relations. Filesystem and Git views are projections.
- `kin git export --output ../repo.git` writes a new bare Git projection from
one graph-owned authority generation. It does not consult working files or an
ambient `.git/` object store, and it refuses an existing or in-repository
destination. Objects, refs, and directories are flushed before the
no-replace destination publication is acknowledged. Capability-anchored
publication is currently available on Unix hosts; other hosts refuse before
creating the export.
This lets a team migrate an existing repository without giving up its editor,
compiler, build system, or Git interoperability while Kin becomes authoritative.
## Platform and maturity
The core runtime and the filesystem projection have different support
boundaries:
| Platform | Core Kin runtime | `kin-vfs` projection |
| --- | --- | --- |
| macOS, Apple Silicon and Intel | Native graph, vector, daemon, setup, MCP, and review surfaces ship in the release archive. | Shipped and exercised on both architectures. It uses `DYLD_INSERT_LIBRARIES`; SIP-protected or hardened programs may reject injection. |
| Linux x86_64 and arm64 | `kin` and `kin-daemon` are static musl builds intended to run on glibc and musl distributions. | The public VFS executable and shim are GNU/glibc builds, not musl builds. They are built against a pinned glibc floor of 2.31 and link OpenSSL 3, so a projection host needs both; Debian 12 loads them, and Alpine and other musl distributions are not supported projection hosts. The release refuses to publish a Linux archive whose binaries ask for more glibc than that floor. The arm64 release proof runs on Ubuntu 24.04. |
| Native Windows x86_64 | Early support: repositories admit and graph and lexical queries answer natively, but MCP and review workflows are not yet covered end to end by the install proof. WSL2 remains the recommended path for full Kin. | Not shipped. Use WSL2 with a Linux distribution that meets the glibc boundary for projection. |
The graph is the authority in every case above. The shim, an NFS mount, a FUSE
mount, and Windows ProjFS are four ways to see that truth as files, and Kin
picks between them by probing what this host can run: a mount where one is
available, because the kernel serves it and no process can have it stripped,
with the injected shim as the compatibility fallback on macOS and Linux and
ProjFS leading on Windows, where no shim exists. `kin vfs on` engages the chosen
one, `kin vfs off` disengages it, and `kin doctor` carries a row saying which is
in force and whether it is working. Where a mode is missing, Kin prints the
exact line that installs or enables it for your platform.
[docs/projection.md](docs/projection.md) has the full per-platform table.
First indexing reads the entire reachable Git history, so `kin init` on a
large or long-lived repository takes minutes, not seconds, before embedding
begins. After `init` returns, the daemon continues preparing in the
background, and the first agent calls on a large repository can take
noticeably longer to answer.
Bounded arm64 testing found the core graph and lexical path usable at 512 MB,
but full embedding downloads a roughly 522 MB model and currently needs 2 GB as
the safe operating floor; 1 GB is an unsafe edge and 512 MB can terminate during
embedding. These are observed alpha constraints, not universal sizing promises.
A successful `kin --version` establishes only that the core binary runs. It
does not establish VFS compatibility or a live graph-backed projection. On a
supported Unix host, use `kin vfs status`, which probes each projection mode and
prints what is actually in force, then `kin setup status` and a real
`kin-vfs exec --workspace . -- <command>` launch. The VFS launcher includes an
interposition canary and reports when the operating system strips the shim.
The [kin-vfs README](https://github.com/firelock-ai/kin-vfs#current-platform-and-package-boundaries)
contains the full boundary.
Release assets are checksum-published and the release workflow runs anonymous
installation, daemon/MCP, embedding, and real graph-backed VFS projection checks
across its supported runner matrix. The workflow itself is public:
[Install Proof](https://github.com/firelock-ai/kin/actions/workflows/install-proof.yml).
A green release establishes those exact artifacts and environments; it is not a
claim that every distribution, tool, or repository shape is already covered.
## FAQ
### Does Kin replace Git?
Beside Git today. Repository authority over time. Git stays an explicit
import/export interoperability boundary during brownfield adoption, so a team
can migrate an existing repository without giving up its editor, compiler,
build system, or Git interoperability.
### Does my code leave my machine?
Kin keeps local repository work in your environment, so repository ingestion,
graph storage, and local queries all run there. KinLab is a separate product
that adds hosted collaboration under explicit access and early-access
agreements.
### Which agents does it work with?
Working with Claude Code, Codex, Cursor, Gemini and anything else that speaks MCP
stays first class. `kin setup --intent agent` configures every client it detects
in one pass.
### Does it block a merge?
Review is advisory, so it flags risk without blocking and the merge decision
stays with your team. `kin review shadow` hands evidence to a human or a CI
policy and stops there.
## Proof posture
The published preregistered Multi-SWE-Bench Go proof package is pinned to an
older build, not the moving latest release, and does not establish a broad
speed, token-savings, or category-win claim. Comparative results are withheld
here pending independent verification.
Read the methodology, task set, build identity, and artifacts in the
[public proof package](https://firelock.ai/labs/kin-proof). Treat claims outside
that measured scope as hypotheses until they have their own reproducible proof.
## Writing
Engineering notes from building Kin, written down so a stranger can reuse them,
live at [kinlab.ai/blog](https://kinlab.ai/blog) with a feed at
[kinlab.ai/rss.xml](https://kinlab.ai/rss.xml).
- [The check that passed because it measured nothing](https://kinlab.ai/blog/checks-that-cannot-fail)
- [Your code search says nothing uses it. Can you delete it?](https://kinlab.ai/blog/empty-answer-safe-to-delete)
## Learn and contribute
- [Quickstart and advanced configuration](docs/quickstart.md)
- [CLI reference: every command, with its flags and defaults](docs/cli-reference.md)
- [Store size and what drives it](docs/store-size.md)
- [MCP tool reference](docs/mcp-tools.md)
- [Language support and what each tier extracts](docs/language-support.md)
- [Environment variable reference](docs/env-vars.md)
- [Graph-first thesis](docs/thesis.md)
- [Write-authority model and its transitional state](docs/write-authority-model.md)
- [GitHub Discussions](https://github.com/firelock-ai/kin/discussions)
- [Bug reports and feature requests](https://github.com/firelock-ai/kin/issues/new/choose)
- [Contributing guide](CONTRIBUTING.md)
- [Private security reporting](SECURITY.md)
## License
[Apache-2.0](LICENSE).
<p align="center"><em>Software that remembers itself.</em></p>