How Kairn Works

Kairn turns the current checkout into compact evidence for a supported coding agent.

The core flow is:

local repository map → bounded evidence candidates → local ranking → safety decision → hook or MCP delivery

Local repository map

Kairn keeps cheap file, symbol, source-role, and direct relationship metadata so it can retain repository-wide recall without loading every chunk or graph edge into user-facing paths.

The index stays on your machine.

Evidence candidates

Kairn begins with strong local signals such as:

• explicit paths and basenames
• exact and prefix symbols
• failure paths and line references
• lexical matches
• git diff and working-tree state
• files already active in the session
• direct import and source/test relationships

It expands only a bounded, query-local candidate set.

Ranking and safety

The current beta ranks repository evidence locally and applies deterministic rules for explicit paths, failures, generated or vendor content, source/test intent, repeated evidence, and context budgets.

A calibrated local relevance ranker is planned for v0.3. It will not become the default until repository-disjoint holdout tests meet source-recall, calibration, latency, state-size, and final-quality gates.

The ranker answers which files are likely required. Deterministic policy separately decides whether to send content, send a path hint, request missing evidence, shrink prior context, or stay silent.

Session state

Kairn records what source evidence has already been delivered, edited, or verified. This helps avoid reopening unchanged content across turns while allowing rereads after edits, new failures, or failed verification.

Delivery paths

Codex CLI is the most-tested public beta path. Local MCP is the portable path for supported editor and agent clients.

Kairn does not need access to an agent's private reasoning loop. It provides repository evidence beside the agent through local hooks and MCP interfaces from the source checkout.

Non-goals

Kairn is not building reasoning-trace capture, model routing, hosted collective memory, trajectory dashboards, general agent orchestration, or a replacement coding agent.

Privacy

Source, prompts, diffs, paths, filenames, repo names, branch names, and agent trajectories are not sent to Kairn by default. Optional aggregate product telemetry is off until explicitly enabled.