Kairo

Kairo

> Persistent engineering memory and session-continuity for AI coding agents. > Local-first. Deterministic. Replay-safe.

[](https://github.com/sandeepbollavaram/Kairo/actions/workflows/ci.yml) [](https://www.npmjs.com/package/kairo-mcp) [](https://www.npmjs.com/package/kairo-mcp) [](https://github.com/sandeepbollavaram/Kairo/releases) [](tests) [](docs/adr) [](docs/APISTABILITY.md) [](docs/APISTABILITY.md) [](package.json) [](tsconfig.json) [](docs/ARCHITECTURE.md) [](docs/adr/0001-event-sourced-storage.md) [](LICENSE)

Kairo sits between AI coding agents — Claude Code, Cursor, Codex, Gemini CLI — and your repository. It is the layer that remembers: a senior engineer's notebook the agent reads at the start of every session and writes to throughout.

It does not run agents. It does not call a model. It runs next to the agent, on your machine, and gives it the durable memory a model cannot keep on its own.

your repo ──▶ AI agent ──▶ Kairo (MCP) ──▶ .kairo/ on local disk
                  ▲                          │
                  └──── continuation brief ◀─┘
                       (resume, don't rescan)

---

10-second pitch

AI coding agents forget. Kairo remembers — durably, deterministically, locally.

1-minute pitch

Every new agent session starts by re-deriving the repo: which files exist, which framework, what the entry points are. That's wasteful, slow, and context-window-hostile. Mid-task the agent runs out of context and stops without a clean handoff. The next agent starts from zero.

Kairo records what happens during a session (file changes, decisions, errors, risk assessments), writes durable checkpoints, and hands the next session an exact continuation brief — "here's what was being done, here's where it stopped, here are the files to look at first". Same project, next agent, no rescan.

5-minute pitch — how it works

| Layer | What it does | Where it lives | | ----------------------- | -------------------------------------------------------------- | ------------------------------------- | | MCP server | 42 tools the agent calls during work. | stdio, launched by your MCP host. | | Session ledger | Append-only log of events, decisions, errors. | .kairo/events.jsonl | | Checkpoints | Durable, sanitized, resumable snapshots. | .kairo/checkpoints/*.json | | Continuation briefs | Markdown handoffs in three size modes. | .kairo/continuations/*.md | | Repo intelligence | Cached fingerprint + framework/language/entry-point detection. | .kairo/intelligence/latest.json | | Vector memory | Architecture-aware hybrid recall (deterministic by default). | .kairo/vector/index.json | | Graphs | Mermaid module / service / architecture diagrams. | .kairo/graphs/*.md | | Inspect surfaces | Read-only HTTP + VS Code views. | kairo inspect, extensions/vscode/ |

Every persisted artefact carries a schema version. Reads validate at the storage seam; corrupt lines go to .kairo/quarantine/; migrations are pure functions. The full architecture sits in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

---

Why AI coding breaks at scale (the honest version)

| Failure mode | Why it happens | What Kairo does about it | | --------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- | | Rescan every session | Agents have no durable scratch space. | kairo_session_start returns cached RepoIntelligence + prior continuation brief. | | Hit context window mid-task | Long sessions exceed any model's window. | Pressure model + CHECKPOINT_NOW directive → safe handoff before crash. | | Repeat past mistakes | Agents don't remember last week's decisions. | Decisions, errors, risk assessments persisted to event log. | | Lose architectural understanding | Agent re-derives layout from scratch. | Pre-computed module + service + architecture graphs available on read. | | No-context handoff between agents | Switching from Claude to Cursor = start over. | Continuation brief works for any MCP-speaking agent. | | Cross-worker conflicts | Two devs/agents touching the same module. | Cooperative file leases (kairo_lease) — explainable, no consensus needed. | | Token cost of "remember everything" | Naive memory layers bloat every prompt. | Brief modes: tiny (1500 chars), normal (4000), deep (20000). |

Kairo is cooperative, not omniscient. It cannot force an agent to stop. It makes losing context expensive and safe handoff cheap. That is achievable and genuinely valuable — and we would rather document the limit than oversell.

---

What Kairo is NOT

Five boundaries on the front page so they aren't buried in an ADR:

1. Not distributed consensus. Coordination is cooperative-on-shared-storage

(file leases over .kairo/), not Paxos/Raft.

1. Not SaaS. No accounts, no hosted backend, no remote telemetry. .kairo/

lives on the local filesystem.

1. Not autonomous AGI orchestration. Kairo is memory + continuity. The

agent decides; Kairo records and advises.

1. Not guaranteed semantic truth. Vector recall is hybrid + salience-ranked;

the deterministic default is honestly lexical/structural.

1. Not real-time collaborative editing. No streams, no push, no live

cursors. Historical inspection + cooperative coordination.

Out of scope by design, not deferred.

---

Quick start (60 seconds)

In any project:

# 1. Install (globally, so the `kairo` binary lands on PATH)
npm install -g kairo-mcp

# 2. Wire it into your MCP host (Claude Code, Cursor, etc.)
cd your-project
kairo init

# 3. Verify
kairo doctor

> Don't want a global install? Use npx -p kairo-mcp kairo init. The > -p kairo-mcp flag tells npx "fetch the kairo-mcp package and run the > kairo bin from it" — needed because npm packages can have multiple bins > and npx defaults to the bin matching the package name (which here > is the MCP server, not the CLI). Once you've used npx once it's cached; > subsequent calls are instant.

> Want the pre-release / dev tip? npm install -g github:sandeepbollavaram/Kairo > builds from the latest commit on main instead of the published npm > version. Same kairo CLI; identical behaviour.

kairo init works in any project type — Node, Python, Rust, Go, empty, anything. It detects your environment and picks the most reliable way to launch the MCP server (since v1.4.0):

| Detected environment | .mcp.json form | When this fires | | ----------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------- | | ./node_modules/kairo-mcp/dist/index.js exists | node ./node_modules/kairo-mcp/dist/index.js | Node project that ran npm install kairo-mcp locally. | | kairo-mcp on PATH | command: "kairo-mcp" | Any project after npm install -g kairo-mcp (recommended). | | neither | npx -y kairo-mcp | Empty repo, Python repo, no install at all. npx fetches on first run. |

Output looks like:

Initialised
  .mcp.json:   written
  mcp form:    global (kairo-mcp on PATH)
  .gitignore:  appended
  mcp host:    claude

Next steps
  1. Open Claude Code in this project: claude
  2. Inside the session, run: /mcp
     → you should see  kairo · connected · 42 tools
  3. If anything looks off, run: kairo doctor

kairo doctor is your one-stop check:

Doctor
  ok  project root           /your/project
  ok  kairo-mcp installed    ./node_modules/kairo-mcp/dist/index.js
  ok  .mcp.json wires kairo  ./.mcp.json
  !!  .kairo/ present        (none yet — first MCP session creates it)
  ok  quarantine empty       clean
  ok  version match          installed=1.2.0 cli=1.2.0

next: 1 check(s) need attention.

(The .kairo/ warning is expected — the first agent session creates it.)

Open Claude Code in the project, run /mcp, you'll see kairo · connected. Then say "start a Kairo session and help me with X."

---

Real workflow

$ cd flexdee-monorepo
$ npx kairo init
Initialised
  .mcp.json:   written
  .gitignore:  appended
  mcp host:    claude

Next steps
  1. Open Claude Code in this project: claude
  2. Inside the session, run: /mcp
     → you should see  kairo · connected · 42 tools
  3. If anything looks off, run: kairo doctor

# ── Day 1: open Claude Code, work for an hour, end the session ────────
$ npx kairo status
Project
  root              S:\projects\flexdee-monorepo
  events            47
  telemetry         12
  sessions          1
  checkpoints       2
  quarantine        0
  latest session    01JD8VK7HQM…
  latest checkpoint 01JD8WPCXNE…

Intelligence
  schema     v4
  files      842
  frameworks express, nextjs, prisma
  languages  TypeScript, JavaScript, SQL

# ── Day 2: see exactly what the next agent will resume from ───────────
$ npx kairo brief --tiny
# Kairo Continuation Brief (tiny)

- **Task:** wire idempotent payment retries
- **Stop point:** session-end · risk HIGH · pressure CONTINUE
- **Files changed:** 3 — top: src/payment/charge.ts, src/payment/retry.ts
- **Next:**
  1. Resolve the 1 unresolved error(s) before new feature work.
  1. Re-validate high-risk changes before proceeding: src/payment/charge.ts.
- **Critical warnings:**
  - ⚠️ integration test flakes on retry path

# ── Inspect everything in your browser ────────────────────────────────
$ npx kairo inspect
ready http://127.0.0.1:4173
  project: S:\projects\flexdee-monorepo
  read-only · no network · Ctrl+C to stop

---

Token reduction example

Same checkpoint, three modes — measured on Kairo's own repo:

| Mode | Chars | % of deep | Use when | | ------------------ | ----: | ----------: | ---------------------------------- | | tiny | 632 | 15% | Pre-empt rescans on cheap startup. | | normal (default) | 2,946 | 71% | Resumes / checkpoints. | | deep | 4,146 | 100% | Explicit historical review. |

$ npx kairo brief --tiny    # 632 chars
$ npx kairo brief           # 2946 chars (normal)
$ npx kairo brief --deep    # 4146 chars
$ npx kairo brief --max-chars 1000  # exactly 1000 chars, truncated cleanly

Truncation is preservation-aware: critical sections (task, stop point, top changed files, next actions, warnings) are front-loaded so tail clipping keeps the load-bearing content.

---

Continuation example

After a session ends, Kairo writes a markdown brief. The next agent reads it on kairo_session_start instead of re-deriving the repo:

# Kairo Continuation Brief

> Resume from this brief. Do **not** rescan the whole repository —
> inspect only the files listed below unless they prove insufficient.

- **Generated:** 2026-05-21T14:30:00.000Z
- **Checkpoint:** `01JD8WPCXNEPC0G7N4DXKDKMG6` (manual)
- **Context-loss pressure:** 0.21 → CONTINUE

## Task

wire idempotent payment retries

## Engineering risk at checkpoint

**HIGH** (score 0.6875).

- [HIGH] src/payment/charge.ts (modified) is in a high-risk area

## Files changed this session — inspect these first

| File                    | Change   | Risk | Touches |
| ----------------------- | -------- | ---- | ------- |
| `src/payment/charge.ts` | modified | HIGH | 3       |
| `src/payment/retry.ts`  | created  | HIGH | 1       |

## Key decisions

- **Idempotency via request UUID** — prevents double-charges on retry.

## Recommended next actions

1. Resolve the 1 unresolved error(s) before new feature work.
1. Re-validate high-risk changes before proceeding: src/payment/charge.ts.

## Semantic architecture recall

- **checkpoint 01JD8WPCXN…** (session, score 3.119) — salience 0.86, similarity 0.59
- **src/payment** (structural, score 1.71) — runtimeLayer 1, dependencyProximity 0.83

---

Graph example

$ npx kairo graph module

flowchart TD
  api[src/api] --> payment[src/payment]
  api --> auth[src/auth]
  payment --> shared[src/shared]
  auth --> shared
  payment --> db[(prisma)]

The same file lives at .kairo/graphs/module.md — kairo inspect renders it in the browser via its Mermaid source.

---

Snapshot / recovery example

# Archive the current state as one portable JSON file:
$ npx kairo snapshot export
  path:        S:\...\flexdee\.kairo\snapshots\snapshot-2026-05-21....json
  bytes:       187,206
  sha256:      df54fa6c84b2a91f3...
  events:      47
  checkpoints: 2
  sessions:    1

# Move it to another machine, then:
$ npx kairo snapshot import ./snapshot.json
  target:        /new/machine/path
  events:        47
  sessions:      1
  checkpoints:   2
  continuations: 2

Snapshots are content-hashed: two exports of the same .kairo/ produce byte-identical files. Use for backups, sharing with teammates for triage, or moving engineering memory between machines.

---

Multi-agent coordination example

When two agents share a .kairo/, cooperative leases keep them from stepping on each other:

// agent A
{ "name": "kairo_lease", "arguments": {
    "action": "acquire", "scopeKind": "path", "scope": "src/payment"
}}
// → { "granted": true, "reason": "Lease granted on path:\"src/payment\"" }

// agent B (1 minute later)
{ "name": "kairo_lease", "arguments": {
    "action": "acquire", "scopeKind": "path", "scope": "src/payment"
}}
// → { "granted": false, "conflict": {...}, "reason":
//      "Scope path:\"src/payment\" is leased by worker \"agent-A\" until …
//       Coordinate or wait — Kairo advises, it does not preempt." }

This is cooperative, not consensus. Two agents on a shared filesystem observe the same event log and agree to back off. No network protocol, no master. The same model also keeps cross-worker semantic memory namespace- isolated (one agent's private chunks don't leak to another).

---

VS Code integration

A separate publishable extension under [extensions/vscode/](extensions/vscode/). Activity-bar tree views for:

• Overview (counts)
• Sessions (newest first)
• Checkpoints (click → opens the continuation brief)
• Active leases
• Risk escalations

Reads .kairo/ directly via fs — does not spawn the MCP server. Auto-refreshes on changes via vscode.workspace.createFileSystemWatcher.

# Build the extension locally
cd extensions/vscode
npm install && npm run build
# then F5 in VS Code to "Run Extension"

> (Cursor: same extension works — Cursor is a VS Code fork.)

---

Inspect surface

Browser-based read-only inspector. No remote assets. Every route except /atlas* is JS-free with CSP default-src 'none'; /atlas* carries a scoped script-src 'self' policy (see [Kairo Atlas](#kairo-atlas)). Useful for triage, debugging, demos.

$ npx kairo inspect
ready http://127.0.0.1:4173

Routes: /, /sessions, /sessions/:id, /checkpoints, /checkpoints/:id, /continuations/:name, /timeline, /graphs, `/graphs/:kin

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sandeepbollavaram
• Source: sandeepbollavaram/Kairo
• License: MIT

Install and usage instructions live in the source repository linked above.