{ "markdown": "

\n \"Kin,\n

\n\n
\n\n

The diff is not the change.

\n\n

The system of record for AI-written software.

\n\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) [![Latest release](https://img.shields.io/badge/release-latest-6E56CF.svg)](https://github.com/firelock-ai/kin/releases/latest) [![kinlab.ai](https://img.shields.io/badge/hosted-kinlab.ai-111111.svg)](https://kinlab.ai)\n\n
\n\nAI writes a change in seconds. Working out what it touches has not gotten any\nfaster.\n\nEvery agent reads a repository the way a person would. Search, open files,\nfollow callers, build the picture, throw it away when the session ends. The\nnext one starts over. The reviewer starts over again. Most AI tools rebuild\ncontext for each task. Kin keeps a durable semantic record across tasks,\nagents, and changes.\n\nGit shows which lines changed. Kin shows what the change affects.\n\nKin makes the graph the repository. Entities, relationships, exact source, and\nchange history are what you commit, branch, and merge, and files stay a\nprojection so ordinary tools keep working.\n\nAgents stop rebuilding context and start editing code. Reviewers see what a\nchange touches before it merges.\n\nKin is a public alpha. It runs today as a local CLI, a daemon, an MCP server for\nagents, a review surface, and a graph-backed filesystem projection. It is\npre-1.0, so expect rough edges and breaking changes. See the\n[latest stable release](https://github.com/firelock-ai/kin/releases/latest) and\n[what is real today and what is alpha](#what-is-real-today-and-what-is-alpha) before\nyou put it in a critical workflow.\n\nPoint it at a repository you know and ask it something you already know the\nanswer to. Or watch it run on Kin's own repositories at\n[kinlab.ai/demo](https://kinlab.ai/demo).\n\n## See it on a real repository\n\nA one-line signature change in ripgrep looks harmless in the diff. Ask\n`kin impact` about it, before any compiler runs, and it names what the edit\nreaches. The callers of the changed signature come first, then everything\nthose callers pull in behind them.\n\n

\n \"kin\n

\n\nRecorded against a prepared graph at ripgrep commit\n`e89fff89ac9af12e8d4ce9d5fd07beb408ca730f`. A one-line signature edit, and Kin\nsurfaces the entities it affects before a compiler runs. The graph was built\nbeforehand. No compiler ran. The two commands are the ones in the quickstart\nbelow: `kin init .` to build the graph, then `kin impact` on the entity you\nchanged.\nThe raw run directory for this capture is not public yet, so treat it as a\nrecipe you can re-run rather than a trace you can audit.\n\nKin surfaces what the change touches. Whether the change is correct stays with\nyour compiler, tests, and review. The graph is built beforehand by `kin init`,\nand building it is the expensive part; after that, impact questions are\nanswered from graph truth, not from re-reading the tree.\n\n## Quickstart\n\nInstall, admit your repository, check the graph, ask it something. Wire your\nagent last. The agent tools answer from the graph, so a client pointed at a\nrepository with no graph gets a tool surface with nothing behind it.\n\nRun the installer on its own and finish any setup prompts:\n\n```sh\ncurl -fsSL https://get.kinlab.dev/install | sh\n```\n\nOnce it finishes, reload your shell with this separate command:\n\n```sh\nexec \"$SHELL\" -l\n```\n\nAt the new prompt, replace the path below with your repository's location and\nrun this block:\n\n```sh\ncd /path/to/your/repository &&\nkin init . &&\nkin overview\n```\n\n`kin overview` prints what the graph now holds: entity counts by kind, by\nlanguage, and the files carrying the most of them. If it prints counts, the\ngraph is real and the commands below have something to answer from.\n\nThe rest of this section is the same path with the detail behind each step.\n\n### 1. Install Kin\n\nOn macOS or Linux, run the installer on its own and finish any setup prompts:\n\n```sh\ncurl -fsSL https://get.kinlab.dev/install | sh\n```\n\nOnce it finishes, reload your shell with this separate command:\n\n```sh\nexec \"$SHELL\" -l\n```\n\nThe installer resolves the [latest stable release](https://github.com/firelock-ai/kin/releases/latest),\nverifies its published SHA-256 checksum, installs the managed binaries under\n`~/.kin`, and launches setup. Running the explicit `agent` intent, which\n[step 5](#5-wire-your-agent) does once the graph exists, configures the built-in\nMCP server for detected supported clients. Use `--intent local` for CLI and\nfilesystem use without MCP configuration, or `--intent editor` for the VS Code\npath.\n\nnpm, Homebrew, and a manual archive resolve that same public release channel:\n\n```sh\nnpm install -g @kinlab/kin@latest\nbrew install firelock-ai/kin/kin\n```\n\nEach archive and its `.sha256` file is published under\n`https://github.com/firelock-ai/kin/releases/latest/download/`, and the release\npage lists the asset names.\n\nConfirm what you installed with `kin --version`, whichever path you took.\n[The quickstart doc](docs/quickstart.md#1-install) carries the operator detail:\nthe asset matrix, what to do when a global npm install hits `EACCES`, how the\nHomebrew formula is regenerated from each release rather than hand-maintained,\nand `kin setup uninstall` when you want the integrations gone.\n\nOn Windows, run `irm https://get.kinlab.dev/install.ps1 | iex` in PowerShell.\nNative 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.\nRead [Platform and maturity](#platform-and-maturity) below before choosing a\nWindows install path.\n\n### 2. Admit your repository as graph truth\n\nReplace the path below with your repository's location:\n\n```sh\ncd /path/to/your/repository && kin init .\n```\n\nIn a detected Git repository, `kin init` atomically admits complete reachable\nhistory, refs, raw objects, the exact workspace tree, and admission policy into\nrepository-v6 graph authority. A worktree with uncommitted edits, staged\nchanges, or untracked files still admits: `kin init` admits the committed state\nand discloses what it did not admit. It never substitutes an exact-HEAD snapshot or\nraw-filesystem semantic rebuild. Supported repository-local remote URLs,\nrefspecs, branch tracking, and push defaults are sealed into Kin's Git\ncoexistence configuration; unsafe, ambiguous, or unsupported transfer settings\nfail closed before publication.\n\nAdmission also derives the semantic entity and relation layer for every\nsupported entity-source file in that history, and `kin init` reports the durable,\ngeneration-bound counts it committed. `kin status` reports that repository\nauthority view; `kin graph status` separately reports the daemon's mutable live\nquery graph, which may include later derived enrichment.\nQuery surfaces consume graph-owned enrichment when it exists and report its\nabsence instead of hiding the gap behind raw file search.\n\n`kin init` is the slow step and the one that earns the rest. It admits your Git\nhistory into the graph, and every answer after it comes from that graph rather\nthan from re-reading the tree. Measured on a fresh Debian 12 container with 4\nCPUs and 8 GiB against the release npm serves today, the installer took 4\nseconds, `kin init` took 139 seconds on a 503-file repository with 1,983\ncommits, and the first `kin locate` answered in 6.7 seconds while the daemon\ncold-started, then in 71 milliseconds warm. Those are separately measured legs\nof one sitting, not one timed run, and a repository with deeper history takes\nlonger.\n\n#### Which files become entities\n\n\"Supported entity-source file\" means a file one of Kin's language adapters\nclaims. The adapter registry is the whole set, and every file in a repository\nresolves through it:\n\n| Language | Extensions |\n| --- | --- |\n| TypeScript | `.ts`, `.tsx` |\n| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` |\n| Python | `.py`, `.pyi` |\n| Go | `.go` |\n| Java | `.java` |\n| Rust | `.rs` |\n| C | `.c`, `.h` |\n| C++ | `.cpp`, `.hpp`, `.cc`, `.cxx` |\n| C# | `.cs` |\n| Ruby | `.rb` |\n| PHP | `.php` |\n| Swift | `.swift` |\n| Kotlin | `.kt`, `.kts` |\n| HCL / Terraform | `.tf`, `.tfvars` |\n\nA `.h` header is read as C++ when its contents say so, so a C++ project does not\nlose namespaces and templates to the C grammar.\n\nEverything else is admitted as content and stays queryable as history and text,\nbut is not parsed into entities and relations. That includes Markdown, HTML and\nCSS, SQL, YAML, JSON and TOML, shell scripts, Objective-C, Scala, Elixir, Dart,\nLua, R, Zig, Haskell, and Nix. If your language is on that list, `locate` and\n`refs` will not find symbols in it.\n\n### 3. Check the graph is ready\n\n```sh\nkin graph status\nkin embed\n```\n\n`kin graph status` reports the daemon's live query graph and its coverage.\nAdmission derives the semantic entities, not their vectors, so run `kin embed`\nto add local vector similarity over them and confirm coverage with\n`kin graph status` again.\n\nOne thing to expect on a small repository: `kin init` starts a background\ndownload of the roughly 523 MB embedding model, and a conversion that finishes\nin seconds can beat it. When that happens the first `kin locate` ranks on\nlexical and graph signals alone and says why on the line beneath its rows. If\nthat line reports the model still downloading, run the query again once it\nlands. If it reports that none of it arrived, do not wait on it: `kin embed`\nfetches the rest.\n\n### 4. Ask it something you already know the answer to\n\nThis is the honest way to judge it. Pick a helper you know the callers of, or a\nsubsystem you could describe from memory, and see whether Kin agrees with you.\nA question about code you've never read tells you nothing about whether the\nanswer is right.\n\n```sh\nkin locate \"\"\nkin refs ExactEntityName\nkin trace ExactEntityName\nkin impact ExactEntityName\n```\n\nReplace `ExactEntityName` with a symbol returned by `locate`. `locate` finds the\nentities relevant to an intent, `refs` shows graph-owned callers/importers and\nreferences, and `trace` returns the focal entity plus nearby semantic context.\nOnce embeddings are complete, your configured AI agent can use the vector-backed\n`semantic_locate` tool; `get_context_pack`, `find_references`, and\n`trace_data_flow` expose the graph neighborhood directly.\n\n`impact` walks the other way from `refs` and shows what sits downstream of the\nentity you are about to change. Replace the `locate` string with a behavior you\ncould already point to in the source.\n\n### 5. Wire your agent\n\nNow that the graph exists, point your agent at it:\n\n```sh\nkin setup --intent agent\n```\n\nUse `kin setup --intent editor` for the VS Code path, or `--intent local` for\nCLI and filesystem use with no MCP configuration. Confirm the resulting\nmachine-readable health checklist with `kin setup status --json`.\n[Works with your agent](#works-with-your-agent) has the per-client one-liners\nand the standard MCP entry.\n\n## Why I built this\n\nI work with coding agents a lot, and the same thing kept bothering me. Before an\nagent can change anything, it spends a stretch of its run working out where\nthings live and how they connect. Then the next session does that work again.\nMeanwhile I'm doing a version of it myself, trying to piece together enough of\nthe same picture to review what it actually did. You're paying a tax to\nre-understand what was already understood.\n\nAt some point I started wondering why that structural understanding isn't just\npart of the repository.\n\nGit is a great content tracker. Linus said it himself when he made it: it's a\nstupid content tracker. It only tracks what changed. Kin records the software.\nEverybody is trying to put bolt-ons on top of Git, and I understand why. My\nthesis is that it's the wrong way to store code for the velocity and the way\nwe're doing coding in 2026.\n\nIt's like using a paper map versus Google Maps. Same roads either way. One of\nthem knows where you are and what connects to what.\n\nI've been working on this for six months in my spare time, which has not been\nmuch spare time. I've got a substantial alpha built. I've taken it as far as I\ncan on my own, and I'm ready to let this thing shine. It's just engineering work\nfrom here on.\n\n## What is real today, and what is alpha\n\nReal today. The graph is the repository. Kin has its own commits, branches, and\nmerges, with Git import and export beside them. The exact source is preserved\nbyte for byte. The CLI, the bundled MCP server, and the VS Code extension all\nanswer from that same graph. Local repository work runs on your machine.\n\nThese are the limits worth knowing before you start.\n\n**Admission holds every commit's tree at once.** `kin init` materializes one\nresolved tree per commit and keeps every one of them, so what a conversion needs\nfollows history depth multiplied by tree size. On a history too long for the\nmachine, Kin refuses in words with a memory forecast, before it captures\nanything, rather than dying partway. Commits multiplied by tracked files is the\nnumber that decides it. Measured against the release npm serves today, refusal\nstarts somewhere above 6.44 million on a 16 GB machine and 12.88 million on\n32 GB. `redis/hiredis`, 1,390 commits over 79 files, admits in under three\nminutes and leaves a 310 MB store. `axios`, 2,180 commits over 466 files, admits\nin about seven minutes. `facebook/react` is 21,679 commits over 7,213 tracked\nfiles, which is 156 million, and a normal clone of it is refused. A shallow\nclone is not the way around it: `git clone --depth` leaves a boundary Kin\nrefuses, because a\nhistory whose oldest commits have absent parents cannot be captured losslessly.\nThere is no partial-history mode.\n\n**Some repositories refuse to import at all.** Repositories carrying submodules\nor Git LFS are refused before admission. Kin does not model submodules yet, so\nrefusing is the correct answer rather than a silent partial import.\n\n**Git export names Kin as the author's mailbox.** `kin git export` writes native\nKin commits with the author's name and `kin@localhost` as the email, and no\nsign-off trailer. Commits that came in from Git are reused as their original\nobjects, so their identity is untouched.\n\n**`kin init` adds exactly one ignore rule.** It writes `/.kin/` into\n`.git/info/exclude`, which is local to your checkout, and leaves your tracked\n`.gitignore` alone. Whether a teammate's checkout carries a Kin store is their\nbusiness, not a tracked file's.\n\n**Not every language becomes entities.** The adapter table in\n[step 2](#which-files-become-entities) is the whole set. Everything else is\nadmitted as content and stays queryable as history and text, but `locate` and\n`refs` will not find symbols in it.\n\n**The graph can still miss relationships.** Coverage is real and it is not\ncomplete, so treat an empty answer as a question rather than as a proof. You\nstill need your compiler, your tests, and your own judgment.\n\n**No format change ships without a migration path.** No release will drop an\nexisting store without a tested migration path. A repository admitted from Git\ncan always be re-admitted from Git. State that exists only in Kin will be\ncarried forward by an upgrade command shipped with any format change, or the\nformat change does not ship. A format change never rewrites your working tree.\n\nWhat that recovery looks like, measured on a 261-commit repository: delete\n`.kin`, run `kin init` again, and everything Git holds comes back, all 61 refs\nbyte-identical. Nothing native comes back. A commit, a branch, a review, and a\nspec that existed only in Kin were gone, while the edited file survived as an\nuncommitted working-tree change. Re-admission also mints a new repository id\nunless you pass `--adopt-repository-id`. That is the gap the upgrade command\nabove exists to close.\n\n[Platform and maturity](#platform-and-maturity) below has the per-platform\nboundaries, the memory floors, and what a green release does and does not\nestablish.\n\n## The stack\n\nKin is one system with a few clear public surfaces:\n\n| Surface | What it does |\n| --- | --- |\n| **[kin](https://github.com/firelock-ai/kin)** | Semantic system of record: CLI, daemon, graph lifecycle, MCP, review, provenance, and Git coexistence. |\n| **[kin-vfs](https://github.com/firelock-ai/kin-vfs)** | Projects graph-owned files through normal filesystem calls so existing tools can keep using files. |\n| **[kin-editor](https://github.com/firelock-ai/kin-editor)** | VS Code access to the entity explorer, semantic search, trace, review, and rename surfaces. |\n| **[Kin MCP](docs/mcp-tools.md)** | Typed graph tools for AI agents, bundled into `kin` and launched with `kin mcp start`. |\n| **[KinLab](https://kinlab.ai)** | Hosted collaboration and control plane. Public repository connection is not a first-run flow yet. |\n\n## How the pieces fit\n\nKin is the system of record for AI-written software, and everything in the map\nbelow either reaches that authority or supports it. Humans and AI agents come in\nthrough the CLI, the bundled MCP server, or the VS Code extension. All\nthree ask the same daemon, and the daemon answers from graph authority rather\nthan by re-reading the tree. `kin-vfs` projects that same graph back through\nordinary filesystem calls, so editors, compilers, and build systems keep seeing\nfiles. Git sits beside the graph as an import and export boundary rather than as\nan answer path, and KinLab is the hosted layer over the same authority.\n\n```mermaid\nflowchart TD\n people[\"Humans and AI agents\"]\n\n subgraph surfaces[\"Access surfaces\"]\n cli[\"kin CLI\"]\n mcp[\"Kin MCP server\"]\n editor[\"kin-editor for VS Code\"]\n end\n\n daemon[\"kin daemon\"]\n authority[\"Graph authority
entities, relations, changes, provenance\"]\n db[\"kin-db
graph storage, snapshots,
index, text and vector search\"]\n prims[\"kin-model, kin-blobs, kin-search,
kin-vector, kin-infer, kin-lsp\"]\n vfs[\"kin-vfs
transparent file projection\"]\n tools[\"Editors, compilers, build systems\"]\n git[\"Git
import and export boundary\"]\n kinlab[\"KinLab
hosted collaboration and control plane\"]\n\n people --> cli\n people --> mcp\n people --> editor\n cli --> daemon\n mcp --> daemon\n editor --> daemon\n daemon --> authority\n authority --> db\n db --> prims\n authority <-->|\"kin init imports, kin git export\"| git\n authority -->|\"publish and sync\"| kinlab\n authority --> vfs\n vfs --> tools\n```\n\nUnderneath those surfaces are the layers the system is built from:\n\n| Layer | Role |\n| --- | --- |\n| **[kin-db](https://github.com/firelock-ai/kin-db)** | Graph storage, snapshots, indexing, text search, and vector search. |\n| **[kin-model](https://github.com/firelock-ai/kin-model)** | Canonical types and domain models shared across the stack. |\n| **[kin-blobs](https://github.com/firelock-ai/kin-blobs)** | Content-addressable blob storage. |\n| **[kin-search](https://github.com/firelock-ai/kin-search)** | Lexical search primitives and staged retrieval. |\n| **[kin-vector](https://github.com/firelock-ai/kin-vector)** | Vector and nearest-neighbor substrate. |\n| **[kin-infer](https://github.com/firelock-ai/kin-infer)** | Inference and embedding substrate. |\n| **[kin-lsp](https://github.com/firelock-ai/kin-lsp)** | Language-server enrichment feeding the semantic layer. |\n\nThese are implementation layers of one system, not separate products a new user\nneeds to assemble. None of them is installed separately.\n\n## Open source and the Kin ecosystem\n\nThe core of Kin is open source under Apache-2.0: [kin](https://github.com/firelock-ai/kin),\n[kin-db](https://github.com/firelock-ai/kin-db), [kin-vfs](https://github.com/firelock-ai/kin-vfs),\nand [kin-editor](https://github.com/firelock-ai/kin-editor), plus the supporting\nlibraries kin-model, kin-blobs, kin-search, kin-vector, kin-infer, kin-lsp, and\nkin-actions.\n\n[KinLab](https://kinlab.ai) is a proprietary product built on this open core: the\nhosted collaboration and control-plane layer described above.\n\nThe same boundary applies to how benchmark work is shared. The [benchmark\nspecification and a standalone, dependency-free bundle verifier](https://github.com/firelock-ai/kin-bench-spec)\nare public, so a merge-trust benchmark claim can be checked without access to the\nrunner that produced it. The runner and proof infrastructure that produce sealed evidence bundles (the\norchestration, the pinned-release proof gate, and the hosted measurement\nenvironment) remain private for now. The spec and verifier open first; the runner\ncan open later.\n\n## Version control without Git\n\nKin keeps a full change history with no Git underneath it. In an empty\ndirectory with no `.git`, the same binary records changes, branches, merges,\nand history, and Git never runs. This is that loop, with the output it printed\non one real run of a build of `main`. `kin init`, `kin status`, and `kin diff`\nsay more than is shown here; the lines below are theirs, unedited, with the\nrest trimmed.\n\nStart an empty repository and record a first change:\n\n```sh\nmkdir kin-demo && cd kin-demo\nkin init\n```\n\n```\n Authority: repository-v6 (graph-owned)\n Default ref: refs/heads/main\n History: unborn (no synthetic commit)\n Workspace: empty exact tree\n Store size: 17.4 KiB under .kin/ (no Git object store here to compare against)\n```\n\n```sh\ncat > retry.py <<'PY'\ndef backoff(attempt):\n return min(2 ** attempt, 30)\nPY\nkin commit -m \"Add the retry backoff\"\n```\n\n```\n starting the kin daemon for this repository; the first query after a start waits for it to load the graph\n kin daemon ready in 1.8s\nCreated semantic change f635b52070f2944aa1c8651fec50cfa62e1cc21c00760137f62f971a7c27642f on branch 'refs/heads/main' (2 entities, 0 relations, 1 artifacts)\nRecorded in Kin authority, not in git. `git status` stays dirty until you run `kin eject` or push this branch to a Kin remote.\n```\n\nThe first commit starts the repository's daemon. Before that, right after\n`kin init`, `kin status` reports durable authority alone and says so on its\n`Tree:` line; once the daemon is up, every `kin status` measures the working\ncopy. Who made the change comes from your Git identity when you have one, and\notherwise from `default_author` in `.kin/config.toml`. Kin refuses to record a\nchange attributed to nobody.\n\nBranch, change the function on the branch, and commit there:\n\n```sh\nkin branch create cap-backoff\nkin branch switch cap-backoff\n```\n\n```\nCreated refs/heads/cap-backoff at change f635b52070f2944aa1c8651fec50cfa62e1cc21c00760137f62f971a7c27642f (authority generation 3)\nSwitched to refs/heads/cap-backoff at change f635b52070f2944aa1c8651fec50cfa62e1cc21c00760137f62f971a7c27642f (1 projected entries, authority generation 4)\n```\n\n```sh\ncat > retry.py <<'PY'\ndef backoff(attempt):\n \"\"\"Exponential backoff, capped at a minute.\"\"\"\n return min(2 ** attempt, 60)\nPY\nkin status\n```\n\n```\nKin repository-v6 status\nHead: symbolic refs/heads/cap-backoff\nTree: 198609d9406becdd1fb97f1f3d16d8d869dc382c38823f2b88aa75f72d927029 (1 artifacts, ahead of its base change as admitted 0s ago)\nRefs: 2, default refs/heads/main\nDurable semantic enrichment: present (2 entities, 0 relations, 1 changes at authority generation 5, workspace generation 3; completion not attested)\nUntracked host content: none, measured 0s ago\n```\n\n```sh\nkin commit -m \"Raise the backoff cap to a minute\"\n```\n\n```\nCreated semantic change 64cce9085641a7eee86bd2b870567ac524835e2e80488f7e5444f7cf9b42c065 on branch 'refs/heads/cap-backoff' (2 entities, 0 relations, 1 artifacts)\n```\n\nBack on `main`, record a second change so the merge has two real parents, then\nmerge the branch:\n\n```sh\nkin branch switch main\ncat > retry_test.py <<'PY'\nfrom retry import backoff\n\ndef test_first_attempt_waits_one_second():\n assert backoff(0) == 1\nPY\nkin commit -m \"Add a first backoff test\"\nkin merge cap-backoff\n```\n\n```\nSwitched to refs/heads/main at change f635b52070f2944aa1c8651fec50cfa62e1cc21c00760137f62f971a7c27642f (1 projected entries, authority generation 7)\nCreated semantic change 18abd82f3a295696fa4938fc078613c0abe4a3214dd6ec0eb81f8a7c1f747105 on branch 'refs/heads/main' (2 entities, 3 relations, 1 artifacts)\nMerged refs/heads/cap-backoff into refs/heads/main as change 4137af4647e6b838771d5e4ce98d8a604304b9d0a66fdb4e0931e828d6b75c9c (2 projected entries, authority generation 9)\n```\n\nThe merge composed both sides by entity identity against their common base,\nwith no line-level text merge, and published one change carrying both parents.\n`kin log` walks that history and `kin diff` shows what the merge brought in,\nas artifacts, as entities, and as lines:\n\n```sh\nkin log\n```\n\n```\nchange 4137af4647e6b838771d5e4ce98d8a604304b9d0a66fdb4e0931e828d6b75c9c\nAuthor: Kin Demo \nDate: 2026-09-05T01:15:32.635348+00:00\nOrigin: native\nParents: 18abd82f3a295696fa4938fc078613c0abe4a3214dd6ec0eb81f8a7c1f747105 64cce9085641a7eee86bd2b870567ac524835e2e80488f7e5444f7cf9b42c065\nDeltas: entities=2 relations=0 tree=1 policy=false\n Merge refs/heads/cap-backoff into refs/heads/main\n\nchange 18abd82f3a295696fa4938fc078613c0abe4a3214dd6ec0eb81f8a7c1f747105\nAuthor: Kin Demo \nDate: 2026-09-05T01:15:32.339226+00:00\nOrigin: native\nParents: f635b52070f2944aa1c8651fec50cfa62e1cc21c00760137f62f971a7c27642f\nDeltas: entities=2 relations=3 tree=1 policy=false\n Add a first backoff test\n\nchange 64cce9085641a7eee86bd2b870567ac524835e2e80488f7e5444f7cf9b42c065\nAuthor: Kin Demo \nDate: 2026-09-05T01:15:31.791709+00:00\nOrigin: native\nParents: f635b52070f2944aa1c8651fec50cfa62e1cc21c00760137f62f971a7c27642f\nDeltas: entities=2 relations=0 tree=1 policy=false\n Raise the backoff cap to a minute\n\nchange f635b52070f2944aa1c8651fec50cfa62e1cc21c00760137f62f971a7c27642f\nAuthor: Kin Demo \nDate: 2026-09-05T01:15:30.609174+00:00\nOrigin: native\nDeltas: entities=2 relations=0 tree=1 policy=true\n Add the retry backoff\n```\n\n```sh\nkin diff HEAD~1 HEAD\n```\n\n```\nKin repository-v6 diff\nBase: HEAD~1 (e5aa80af2498ad1d8f8c5a756f24467773a7f12c46039395deb691a0e09ff0bc)\nHead: HEAD 4137af4647e6b838771d5e4ce98d8a604304b9d0a66fdb4e0931e828d6b75c9c (f86d6f68558a54372da1c08cedd8549dd98733110e3f2db6193dc8314ba10c11)\nArtifacts: +0 ~1 -0\nEntities: +0 ~2 -0\nRelations: +0 ~0 -0\nM retry.py -> retry.py [aab37f62-f986-4543-8187-4af2b8984e0a] blob 0ceda974a82e648bf6e6d40efccc9489eb4b73fa5ab3f0c5cfd35df4911cd524 mode=100644 -> blob c0b44cec88f49e73cc31f7f439ec1b10d9d73cfe1c414dc539106886d4747cce mode=100644\nE~ 0a69467a-63d6-5c34-ac35-632cefde30b7 retry -> retry\nE~ 6cd876cf-cc8a-50bd-94be-e0a2fde3208d backoff -> backoff\n @@ -1,2 +1,3 @@\n def backoff(attempt):\n - return min(2 ** attempt, 30)\n + \"\"\"Exponential backoff, capped at a minute.\"\"\"\n + return min(2 ** attempt, 60)\n```\n\n`HEAD~1` is the merge's first parent, the test commit, so the diff is exactly\nwhat `cap-backoff` contributed: one artifact, the two entities in it (the\nmodule and the function), and the lines. `kin checkout`, `kin stash`,\n`kin rollback`, `kin blame`, and `kin conflicts` with `kin resolve` round out\nthe set, and `kin capabilities` prints where each one stands.\n[The CLI reference](docs/cli-reference.md#branches-merges-and-exact-trees) has\nevery flag.\n\nSharing a native repository between machines is still in progress, and public\nrepository connection through KinLab is not a first-run flow yet. What the\ntransfer commands do today: `kin clone` takes a KinLab locator or the HTTP\nendpoint of another machine's running Kin daemon, adopts that repository's\nidentity into a fresh local workspace, and remembers the origin it came from.\n`kin push` sends your new changes to that saved origin one verified pack at a\ntime, and refuses rather than forces when the remote has moved past you.\n`kin pull` admits what the origin has that you do not and moves your working\ntree onto it, and when uncommitted work stops the tree from following, it says\nso and keeps the history it received. Each of the three is exercised between two\nKin daemons over HTTP by the test suite.\n\n## Works with your agent\n\nKin ships its own agent, and it's the path I recommend for agent work. `kin\nagent run` drives any OpenAI-compatible endpoint, so a local model in LM Studio,\nOllama, llama.cpp or vLLM works from the same flags as a hosted one, and it\nreaches the graph over the same MCP server every other client uses.\n\n```sh\nkin agent run --task \"Find where the retry backoff is computed and document it\" \\\n --model qwen/qwen3.6-35b-a3b --base-url http://localhost:1234/v1\n```\n\nWhat makes it different from pointing another agent at the MCP server is that the\nrule is enforced inside the agent rather than borrowed from a vendor's permission\nlayer. It has Kin's tools plus exactly two local ones, `edit_file` and\n`write_file`. There is no shell, no grep and no file-reading tool, so it cannot\nanswer a repository question from raw file search, and a tool it invents is\nrefused by name. When Kin reports that an empty result cannot be trusted, the\nagent is told the answer is unknown and given the named gap instead of concluding\nthe thing does not exist. Every edit runs inside a Kin transaction under a Kin\nsession, so the change carries provenance naming the agent. Run `kin agent doctor\n--base-url ` first to check both halves answer. See\n[the CLI reference](docs/cli-reference.md#kin-agent) for the full surface.\n\nWorking with Claude Code, Codex, Cursor, Gemini and anything else that speaks MCP\nstays first class. `kin setup --intent agent` configures every client it detects\nin one pass. These are the per-client one-liners when you would rather install Kin\ndirectly.\n\nRun `kin init .` in the repository before you wire a client, not after. These\ntools answer from the graph, so a client pointed at a directory with no graph\ngets a tool surface with nothing behind it. `kin setup` says so itself: its\nround-trip check reports \"no initialized Kin repository at or above\" the\ndirectory it ran in, and tells you to run `kin init` there and re-run setup.\n\nClaude Code, from inside a session:\n\n```\n/plugin marketplace add firelock-ai/kin\n/plugin install kin@kin\n```\n\nCodex:\n\n```sh\ncodex plugin marketplace add firelock-ai/kin\ncodex plugin add kin@kin\n```\n\nGemini CLI:\n\n```sh\ngemini extensions install https://github.com/firelock-ai/kin\n```\n\nCursor takes a one-click install link. Paste this into Cursor or into your\nbrowser's address bar:\n\n```\ncursor://anysphere.cursor-deeplink/mcp/install?name=kin&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBraW5sYWIva2luIiwibWNwIiwic3RhcnQiXX0=\n```\n\nKiro takes the same thing as a web link:\n[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).\n\nCline takes the standard entry below rather than a one-liner. Its CLI reads\n`~/.cline/mcp.json`. In the VS Code extension, open the MCP Servers panel, then\nthe Configure tab, then Configure MCP Servers, and add the entry there.\n\nEvery other client that reads a standard MCP config takes this entry:\n\n```json\n{\n \"mcpServers\": {\n \"kin\": { \"command\": \"npx\", \"args\": [\"-y\", \"@kinlab/kin\", \"mcp\", \"start\"] }\n }\n}\n```\n\n`kin setup status` and `kin doctor` recognize this exact shape, alongside the\nabsolute-path form `kin setup` writes, and grade anything else MISCONFIGURED. Do\nnot shorten `command` to a bare `kin`, because agent clients do not reliably\ninherit your shell `PATH`. `@kinlab/kin-mcp` is the older launcher and keeps\nworking for configurations that already name it; new ones should point at\n`@kinlab/kin`, which ships the same MCP server as one mode of the full CLI.\n\nThe wrapper needs Node 20 or newer, and on its first run it downloads the\nmatching Kin release, verifies its published SHA-256, and caches the binaries per\nuser. Codex CLI wants the same thing as TOML under `[mcp_servers.kin]`.\n\nOne caveat worth repeating: these tools answer from the graph, so the repository\nhas to be admitted with `kin init .` and embedded with `kin embed` before\n`semantic_locate` can rank anything. [llms-install.md](llms-install.md) is that\nwhole path written so an agent can follow it unattended, from a bare machine to a\nfirst verified tool call.\n\n## Review an AI-written change\n\n**AI writes code. Kin proves what changed.**\n\nRun `kin init` on the branch you want to review so the relevant Git history is in\nthe graph, then pass explicit commit SHAs to the report-only shadow gate:\n\n```sh\nkin review shadow \"$(git rev-parse main)..$(git rev-parse HEAD)\"\n```\n\nThe result is `PASS`, `NEEDS ATTENTION`, or `WOULD BLOCK`, and it comes with the\nimpact Kin derived from the graph, the context needed to repair it, and the\nevidence behind both. Authorship is declared, not verified. The command will not\nblock your merge or change graph state. It hands evidence to a human or a CI\npolicy and stops there.\n\n## How Kin relates to Git\n\nBeside Git today. Repository authority over time. During brownfield adoption,\nGit remains an explicit import/export interoperability boundary; it never\nanswers Kin runtime queries or repairs missing graph truth.\n\n- `kin init` imports complete reachable Git history and exact parent edges.\n Kin deliberately has no partial-history or snapshot-only initialization mode.\n- After import, Kin's graph owns repository identity, tree state, history, refs,\n and semantic relations. Filesystem and Git views are projections.\n- `kin git export --output ../repo.git` writes a new bare Git projection from\n one graph-owned authority generation. It does not consult working files or an\n ambient `.git/` object store, and it refuses an existing or in-repository\n destination. Objects, refs, and directories are flushed before the\n no-replace destination publication is acknowledged. Capability-anchored\n publication is currently available on Unix hosts; other hosts refuse before\n creating the export.\n\nThis lets a team migrate an existing repository without giving up its editor,\ncompiler, build system, or Git interoperability while Kin becomes authoritative.\n\n## Platform and maturity\n\nThe core runtime and the filesystem projection have different support\nboundaries:\n\n| Platform | Core Kin runtime | `kin-vfs` projection |\n| --- | --- | --- |\n| 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. |\n| 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. |\n| 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. |\n\nThe graph is the authority in every case above. The shim, an NFS mount, a FUSE\nmount, and Windows ProjFS are four ways to see that truth as files, and Kin\npicks between them by probing what this host can run: a mount where one is\navailable, because the kernel serves it and no process can have it stripped,\nwith the injected shim as the compatibility fallback on macOS and Linux and\nProjFS leading on Windows, where no shim exists. `kin vfs on` engages the chosen\none, `kin vfs off` disengages it, and `kin doctor` carries a row saying which is\nin force and whether it is working. Where a mode is missing, Kin prints the\nexact line that installs or enables it for your platform.\n[docs/projection.md](docs/projection.md) has the full per-platform table.\n\nFirst indexing reads the entire reachable Git history, so `kin init` on a\nlarge or long-lived repository takes minutes, not seconds, before embedding\nbegins. After `init` returns, the daemon continues preparing in the\nbackground, and the first agent calls on a large repository can take\nnoticeably longer to answer.\n\nBounded arm64 testing found the core graph and lexical path usable at 512 MB,\nbut full embedding downloads a roughly 522 MB model and currently needs 2 GB as\nthe safe operating floor; 1 GB is an unsafe edge and 512 MB can terminate during\nembedding. These are observed alpha constraints, not universal sizing promises.\n\nA successful `kin --version` establishes only that the core binary runs. It\ndoes not establish VFS compatibility or a live graph-backed projection. On a\nsupported Unix host, use `kin vfs status`, which probes each projection mode and\nprints what is actually in force, then `kin setup status` and a real\n`kin-vfs exec --workspace . -- ` launch. The VFS launcher includes an\ninterposition canary and reports when the operating system strips the shim.\nThe [kin-vfs README](https://github.com/firelock-ai/kin-vfs#current-platform-and-package-boundaries)\ncontains the full boundary.\n\nRelease assets are checksum-published and the release workflow runs anonymous\ninstallation, daemon/MCP, embedding, and real graph-backed VFS projection checks\nacross its supported runner matrix. The workflow itself is public:\n[Install Proof](https://github.com/firelock-ai/kin/actions/workflows/install-proof.yml).\nA green release establishes those exact artifacts and environments; it is not a\nclaim that every distribution, tool, or repository shape is already covered.\n\n## FAQ\n\n### Does Kin replace Git?\n\nBeside Git today. Repository authority over time. Git stays an explicit\nimport/export interoperability boundary during brownfield adoption, so a team\ncan migrate an existing repository without giving up its editor, compiler,\nbuild system, or Git interoperability.\n\n### Does my code leave my machine?\n\nKin keeps local repository work in your environment, so repository ingestion,\ngraph storage, and local queries all run there. KinLab is a separate product\nthat adds hosted collaboration under explicit access and early-access\nagreements.\n\n### Which agents does it work with?\n\nWorking with Claude Code, Codex, Cursor, Gemini and anything else that speaks MCP\nstays first class. `kin setup --intent agent` configures every client it detects\nin one pass.\n\n### Does it block a merge?\n\nReview is advisory, so it flags risk without blocking and the merge decision\nstays with your team. `kin review shadow` hands evidence to a human or a CI\npolicy and stops there.\n\n## Proof posture\n\nThe published preregistered Multi-SWE-Bench Go proof package is pinned to an\nolder build, not the moving latest release, and does not establish a broad\nspeed, token-savings, or category-win claim. Comparative results are withheld\nhere pending independent verification.\n\nRead the methodology, task set, build identity, and artifacts in the\n[public proof package](https://firelock.ai/labs/kin-proof). Treat claims outside\nthat measured scope as hypotheses until they have their own reproducible proof.\n\n## Writing\n\nEngineering notes from building Kin, written down so a stranger can reuse them,\nlive at [kinlab.ai/blog](https://kinlab.ai/blog) with a feed at\n[kinlab.ai/rss.xml](https://kinlab.ai/rss.xml).\n\n- [The check that passed because it measured nothing](https://kinlab.ai/blog/checks-that-cannot-fail)\n- [Your code search says nothing uses it. Can you delete it?](https://kinlab.ai/blog/empty-answer-safe-to-delete)\n\n## Learn and contribute\n\n- [Quickstart and advanced configuration](docs/quickstart.md)\n- [CLI reference: every command, with its flags and defaults](docs/cli-reference.md)\n- [Store size and what drives it](docs/store-size.md)\n- [MCP tool reference](docs/mcp-tools.md)\n- [Language support and what each tier extracts](docs/language-support.md)\n- [Environment variable reference](docs/env-vars.md)\n- [Graph-first thesis](docs/thesis.md)\n- [Write-authority model and its transitional state](docs/write-authority-model.md)\n- [GitHub Discussions](https://github.com/firelock-ai/kin/discussions)\n- [Bug reports and feature requests](https://github.com/firelock-ai/kin/issues/new/choose)\n- [Contributing guide](CONTRIBUTING.md)\n- [Private security reporting](SECURITY.md)\n\n## License\n\n[Apache-2.0](LICENSE).\n\n

Software that remembers itself.

\n", "bytes": 41291, "sha": "8c424ca6bd63056a8e2bd3431532bac77d850a66d63a47ddf1f95e721bd80719", "repo_slug": "firelock-ai/kin", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_firelock_ai_kin_fd1ae88d/readme" }