# Kairo > Persistent engineering memory & session-continuity control layer for AI coding agents (Claude Code, Codex, Cursor, Gemini), built on the Model Context Protocol. Scans a repo once, remembers architecture/decisions/changes, checkpoints safely, and hands the next agent an exact continuation brief — so agents stop rescanning and losing context. - **Type:** MCP server - **Install:** `agentstack add mcp-sandeepbollavaram-kairo` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [sandeepbollavaram](https://agentstack.voostack.com/s/sandeepbollavaram) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [sandeepbollavaram](https://github.com/sandeepbollavaram) - **Source:** https://github.com/sandeepbollavaram/Kairo ## Install ```sh agentstack add mcp-sandeepbollavaram-kairo ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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/API_STABILITY.md) [](docs/API_STABILITY.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. 2. **Not SaaS.** No accounts, no hosted backend, no remote telemetry. `.kairo/` lives on the local filesystem. 3. **Not autonomous AGI orchestration.** Kairo is memory + continuity. The agent decides; Kairo records and advises. 4. **Not guaranteed semantic truth.** Vector recall is hybrid + salience-ranked; the deterministic default is honestly lexical/structural. 5. **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: ```bash # 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 ```bash $ 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. | ```bash $ 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: ```markdown # 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 ```bash $ npx kairo graph module ``` ```mermaid 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 ```bash # 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: ```jsonc // 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`. ```bash # 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. ```bash $ 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](https://github.com/sandeepbollavaram) - **Source:** [sandeepbollavaram/Kairo](https://github.com/sandeepbollavaram/Kairo) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-sandeepbollavaram-kairo - Seller: https://agentstack.voostack.com/s/sandeepbollavaram - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.