The file-first model is ending. Kin is the first layer of what comes next. Learn more →
← Engineering Blog

Why I Built Kin

Troy Fortin Jr · ·
kin open-source version-control ai

Every developer alive has muscle memory for git add, git commit, git push. Git is one of the most successful tools ever built. It won. So why would anyone try to replace it?

I didn’t set out to replace Git. I set out to solve a problem that Git was never designed to handle: giving AI agents useful context without burning through your entire token budget on irrelevant code.

The Problem

Git tracks lines in files. That model works brilliantly when your primary collaborator is a human reading diffs in a terminal. But the fastest-growing class of code collaborators — AI agents — don’t work that way.

When an AI agent needs to understand a function, it doesn’t want the 2,000-line file that function lives in. It wants the function body, its callers, its dependencies, and maybe the interface it implements. Instead, most agent integrations dump entire files into the context window and hope the model figures out what matters. The result is predictable: wasted tokens, degraded reasoning, and missed connections.

The mismatch runs deeper than context stuffing. When a developer renames processOrder to handle_order and moves it to a new file, Git sees a deletion and an addition. A human reviewer can squint and figure it out. An AI agent? It loses track of the entity entirely. The identity is gone. Every downstream reference is now a mystery.

I kept running into these problems in my consulting work at Firelock. I was building AI-powered systems for clients and watching agents struggle with the same class of failures: bloated context, lost identity, no way to ask “what does this function actually affect?”

Why Existing Tools Fall Short

The natural reaction is to bolt semantic understanding onto Git. That’s what most tools do — RAG-based code search, embedding-powered retrieval, wrapper scripts that try to extract structure from file diffs.

These tools help, but they’re limited by what Git can express. You can’t query “what calls this function?” from a commit hash. You can’t ask “what changed semantically between these two versions?” and get an answer in terms of entities rather than line numbers. Vector search gives you similar code, not the actual dependency graph. And none of these tools can tell you that the function you renamed three commits ago is the same entity you’re looking at now.

The abstraction is wrong. Files are containers, not concepts. Lines are formatting, not meaning. If you want semantic understanding, you need a semantic foundation.

The Kin Approach

So I built one. From scratch, in Rust, with no Git dependency.

Kin is a version control system where the source of truth is a graph of semantic entities — functions, types, classes, modules — and the relationships between them: calls, imports, implements, references. Source files still exist, but they’re projections of this graph, not the primary artifact.

This inversion changes everything:

  • Context delivery is graph traversal, not file dumping. Need to understand a function? Traverse its call graph, pull in signatures for dependencies, respect a token budget. The agent gets exactly what it needs and nothing it doesn’t.
  • Identity tracking survives renames and refactors. Kin computes semantic fingerprints from entity structure, not file paths. Rename a function, move it across files, reformat the code — Kin knows it’s the same entity.
  • Token budgets are first-class. Ask Kin for context with a 4,000-token budget and it will build the most informative pack it can within that limit, prioritizing by graph proximity to your focal point.
  • Review is about entity impact, not line diffs. When you review a change in Kin, you see which entities were modified and what they affect downstream. Not “lines 47-53 changed in utils.ts” but “the validateInput function’s contract changed, impacting 3 callers and 1 API endpoint.”

Architecture in Brief

Kin organizes code understanding into four planes:

  • Semantic Plane — The graph of entities, relationships, contracts, and changes. This is the source of truth. Backed by KinDB, a purpose-built embedded graph engine I built specifically for this workload.
  • Projection Plane — Source files, Git commits, docs, and other rendered views of semantic state. Files are outputs, not inputs.
  • Execution Plane — Workspaces, validation runs, and evidence capture. Proves that changes do what they claim.
  • Control Plane — Reviews, governance, assistant adapters, and benchmarks. Manages quality and trust.

Parsing is powered by Tree-sitter with per-language adapters. A content-addressable blob store (SHA-256 addressed) holds raw source text. The whole thing is 18 Rust crates in a Cargo workspace, designed to be embedded, extended, or run standalone.

For the full architectural deep dive, check out the README.

KinDB: The Foundation Layer

Early on, I tried using existing graph databases — KuzuDB, then evaluated SurrealDB, CozoDB, Neo4j, and IndraDB. None of them could do what I needed at the speed I needed it.

The problem is specific: code graphs have a batch-write, continuous-read pattern. You parse on commit, then query thousands of times between commits. General-purpose graph databases pay a tax for flexibility I don’t need — query language parsing, dynamic schemas, transaction isolation levels designed for concurrent writers. I need one writer and many readers, sub-millisecond lookups, and the ability to handle millions of entities without breaking a sweat.

So I built KinDB. It’s a purpose-built, embeddable graph engine in Rust:

  • HashMap-based adjacency lists with compiled Rust queries — no query language, zero parsing overhead
  • Read-Copy-Update concurrency — readers clone a cheap Arc pointer and never block, even during writes
  • Full-text search via Tantivy and vector similarity via HNSW — both built in, not bolted on
  • Incremental indexing — only changed files trigger re-indexing, dropping a 500K-entity commit from 1.8 hours to under 30 seconds
  • Cryptographic integrity — Merkle DAG verification detects tampering at the entity level

The result: sub-millisecond reads (50-170x faster than KuzuDB), 19x less memory at scale, and concurrent reads that never block during writes. KinDB handles repos from 3,000 entities (zod) to 4.3 million (Linux kernel) without architectural changes.

KinDB is Apache-2.0 licensed and usable independently — any Rust application that needs a fast, typed code graph can embed it without depending on Kin. Details at firelock.ai/labs/kin-db.

What Works Today

Kin is in public alpha. I’m shipping what works and being transparent about what doesn’t yet.

The CLI is functional: kin init, kin commit, kin status, kin trace, kin context, kin diff, kin review, and more. You can initialize a project, parse it into a semantic graph, query entity relationships, build token-budgeted context packs, and review changes at the entity level.

The MCP server works. Any MCP-compatible assistant — Claude Code, Codex, Gemini CLI, Cursor — can query Kin’s semantic graph for context, impact analysis, dead code detection, and review data.

Git interop works. Import your existing Git history into Kin’s graph, or export Kin state back to Git commits. Adoption is reversible: delete .kin/ and your source files are untouched.

Tree-sitter parsing covers TypeScript, JavaScript, Python, Go, Java, and Rust as Tier 1 languages with full entity extraction, relation extraction, and fingerprinting.

The benchmark harness (kin bench) measures context quality, token savings, and development velocity metrics. I’m using it to prove that the approach works quantitatively, not just philosophically.

The graph engine (KinDB) is proven: sub-millisecond reads across entity lookups, reference tracing, and impact analysis. Full-text search and vector similarity are integrated. The benchmark suite validates performance against 10 real open-source repositories with 70 tasks — run on a 5-year-old M1 MacBook Pro under heavy load — and Kin wins 69 of them. ~50% less wall-clock time and ~45% fewer tokens than Git-based approaches.

What’s still hardening: reconciliation edge cases with broken ASTs, semantic merge conflict resolution, multi-workspace coordination, and performance on very large repos. I’m working on it in the open.

What’s Next

The roadmap includes more language support, richer cross-language contracts (OpenAPI, Protobuf, GraphQL, database schema linking), distributed semantic merge, editor integrations, and deeper MCP capabilities for multi-agent workflows.

I’m also investing in native mode — where Kin manages the working directory directly, materializing files from the graph on demand. This enables workflows where AI agents operate on semantic state without ever touching the filesystem. On the engine side, KinDB’s zero-copy persistence roadmap (rkyv + mmap) will drop CLI startup from 800ms to under 1ms.

Try It

Kin is open source under Apache-2.0 — no strings.

git clone https://github.com/firelock-ai/kin.git
cd kin
cargo build --release

Point it at your codebase with kin init and see what your code looks like as a graph.

If you find rough edges, open an issue. If you want to discuss the approach, join us on GitHub Discussions. If you want to contribute, check out CONTRIBUTING.md.

Git changed how we collaborate on code. I think Kin can change how machines understand it.