Kira

# Kira

[![CI](https://github.com/aibenyclaude-coder/Kira/actions/workflows/ci.yml/badge.svg)](https://github.com/aibenyclaude-coder/Kira/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/kira-mcp.svg)](https://www.npmjs.com/package/kira-mcp)
[![npm downloads](https://img.shields.io/npm/dw/kira-mcp.svg)](https://www.npmjs.com/package/kira-mcp)
[![scars absorbed](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Faibenyclaude-coder%2FKira%2Fmain%2Fdocs%2Fstats.json&query=%24.community_scars&label=scars%20absorbed&color=orange)](./skills/scars/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

### Your agent stops repeating its own mistakes.

Every failed retry, every exception, every *"wait — we hit this exact wall last week"* is knowledge your agent throws away when the session ends. Kira keeps it. One MCP install and your agent **records what burned it** (a *scar*), **sees its scars before it works again**, and stops paying for the same mistake twice.

> **Privacy by design.** Personal scars and the lookup-miss log are **local-only — never uploaded, on any tier**. Community telemetry is opt-in and **redacts secrets, paths, and identifiers locally before write AND server-side before storage**. Run `npm run demo:privacy` to see exactly what leaves your machine. Full wire format and opt-out in [PRIVACY.md](./PRIVACY.md).

---

## Install (10 seconds)

Add this snippet to your MCP host config:

```json
{
  "mcpServers": {
    "kira": {
      "command": "npx",
      "args": ["-y", "kira-mcp@latest"]
    }
  }
}
```

That's it. Your agent now has Kira.

<details>
<summary><b>Per-client paths (click)</b></summary>

| Client | Config file |
|---|---|
| **Claude Code** | `~/.claude/settings.json` (global) or `.claude/settings.json` (per-project) |
| **Claude Desktop** | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\Claude\claude_desktop_config.json` |
| **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project) |
| **Cline / Continue** | extension settings → MCP servers |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **VS Code (MCP preview)** | `.vscode/mcp.json` |
| **Goose** | `~/.config/goose/profiles.yaml` (under `extensions:`) |
| **Zed** | `~/.config/zed/settings.json` (`context_servers`) |

The snippet above works as-is in every one of them — just paste it under `mcpServers` (or the equivalent key for your client).
</details>

---

## The loop, in 30 seconds

```text
Monday    agent gates a merge on:  npm run build 2>&1 | tail -1
          exit code comes from tail, not the compiler → broken code reaches main
          └─ kira_record_failure(
               title:   "build gate bypassed: exit code swallowed by pipe to tail",
               instead: "never gate on a piped command without pipefail")

Tuesday   new session, same machine
          └─ session brief: "⚠ You have been burned by this before:
             never gate on a piped command without set -o pipefail"
          agent writes the gate correctly. Zero repeats. Zero wasted tokens.
```

Not a hypothetical — this is the **actual first scar in the database**, recorded by the agent that built this feature, about a mistake it made *while building it*. The next three scars came the same day. The loop works on day one, for a single user, with zero network effects required. [FLYWHEEL.md](./FLYWHEEL.md) documents the full improvement loop.

---

## Tools (10)

| | Tool | What it does |
|---|------|-------------|
| **Personal memory** | `kira_record_failure` | Capture a retry/exception as a personal scar (local-only) |
| | `kira_personal_brief` | Session-start brief of your latest scars — start work already knowing where you got burned |
| | `kira_premortem` | Failure heat-map for a goal *before* starting — "here's where this kind of task has burned you" |
| **Catalog** | `kira_lookup` | Keyword → proven instructions + failure warnings. On a miss, returns scored `near_skills` / `near_scars` instead of a shrug |
| | `kira_get` | Fetch full step-by-step instructions by ID |
| | `kira_route` | Goal → ordered plan with a skill per step |
| **Community** | `kira_share_scar` | Promote a personal scar into a community submission (sanitized; nothing uploads without your click) — earns contributor status |
| **Feedback** | `kira_report` | Report success/retry/failure → feeds the quality loop |
| | `kira_consent` / `kira_status` | Telemetry consent + one-call introspection |

**Auto-firing:** you don't call Kira — Kira's MCP instructions tell your agent when to. Japanese queries are first-class (CJK bigram matching).

### When nothing matches

A lookup miss is not a dead end — it's demand data. Kira returns the closest scored matches, records the miss locally (with *what almost matched*), and the weekly flywheel digest turns repeated misses into alias fixes and new-skill candidates. The catalog learns what people actually ask for.

---

## The catalog layer (community skills & scars)

![Kira Demo](./demo.gif)

38 community skills across deploy / database / auth / payments / UI / testing / CI / infra / mobile / CMS, and 45 community scars — real failure patterns like *"Vercel deploy succeeds but the app crashes: missing env vars"* or *"Auth.js v5 signIn imported from the wrong side"*. `kira_route` turns a goal ("build a web app") into an ordered plan with the right skill and scars per step.

**Community scars are where personal scars graduate to — and the flow is live.** Ask your agent to run `kira_share_scar(scar_id)`: it re-sanitizes your personal scar, generalizes it, and hands you a prefilled submission link (nothing uploads until you click). An intake bot validates the JSON; a human reviews the content; on merge it ships to every Kira user. Prefer forms? [Submit a scar directly](../../issues/new?template=scar-submission.yml).

Every accepted scar earns **contributor status** — sharing is how you get the fresh feed for free (see Contributing below).

---

## How it works

```
Your agent hits a wall            Your agent gets a task
    ↓                                 ↓
kira_record_failure()             kira_premortem(goal) / kira_lookup(keyword)
    ↓                                 ↓
~/.kira/personal-scars/           scars first, then instructions
    ↓                                 ↓
next session: brief surfaces      agent announces → executes → kira_report()
your scars before work starts         ↓
    ↓                             misses + failure notes feed the flywheel
never the same mistake twice      → digest → catalog improvements
```

Skills are natural language Markdown — no executable code, no injection risk.

---

## Why not just CLAUDE.md?

| | CLAUDE.md / .cursorrules | Kira |
|---|---|---|
| Setup | Copy per project | Install once |
| Failure memory | You write it by hand, if you remember | `kira_record_failure` — captured at the moment it happens |
| Recall | You re-read it, if you remember | Surfaced automatically at session start / task start |
| Selection | You choose | Agent chooses, scored |
| Updates | Manual | Automatic (flywheel) |
| Works across AI tools | Tool-specific | Any MCP client |

## Not another "memory MCP"?

There are excellent memory servers (knowledge graphs, session recall, context handoff). Kira is deliberately narrower:

- **Failure-first, not everything-first.** General memory stores what happened; Kira stores *what must never happen again*, in a shape built for avoidance: `mistake` → `instead`, severity, recurrence count. A pre-task heat-map (`kira_premortem`) exists only because the data is failures.
- **Recurrence is measured, not assumed.** Re-recording a similar failure folds into the same scar and bumps `hit_count` — the corpus learns which walls actually get hit, and honest counts are enforced by review.
- **The commons compounds.** Your scar, sanitized and human-reviewed, ships to every install — and earns you the fresh feed ([RECIPROCITY.md](./RECIPROCITY.md)). Memory servers make one agent smarter; a scar corpus makes *every* agent immune.
- **Trust is engineered, not implied.** Corpus text is injected into agents' contexts, so every entry passes a sanitizer-stability gate in CI, natural-language-only rules, and human review ([SECURITY.md](./SECURITY.md)).

If you need general episodic memory, run one of those servers *alongside* Kira — they don't compete for the same job.

---

## Telemetry

Personal scars (`~/.kira/personal-scars/`) and the miss log (`~/.kira/misses.log`) are **local-only and never uploaded**. Community telemetry is separate and consent-gated:

| Mode (`KIRA_TELEMETRY` env, or `kira_consent` MCP tool) | What leaves your machine |
|---|---|
| `off` | Nothing. Local log only. |
| `basic` *(default)* | Anonymous core: skill ID, status, anonymous UUID, kira version, OS family, Node major version, free/pro tier. **No free text.** |
| `full` | Same as basic plus **sanitized** `note` / `context` (secrets, paths, identifiers redacted). |

Full schema, redaction rules, retention, and opt-out instructions: **[PRIVACY.md](./PRIVACY.md)**.

| Env var | Default | Purpose |
|---|---|---|
| `KIRA_TELEMETRY` | (unset → `basic`) | Override consent level for this process: `off`, `basic`, `full`. |
| `KIRA_TELEMETRY_URL` | `https://kira-telemetry.workers.dev/v1/reports` | Endpoint for batch upload. |
| `KIRA_HOME` | `~/.kira` | Where consent state, personal scars, miss log, and flywheel output live. |
| `KIRA_KEY` | (unset → free tier) | Contributor / supporter key — unlocks the fresh community feed. |
| `KIRA_REMOTE_URL` | (unset → no network) | Opt-in corpus feed URL for the free tier (90-day-delayed commons). |

---

## Share a scar, or subscribe, or wait

The corpus is MIT and everything in it eventually becomes free. **Freshness is the only premium** — failure knowledge decays as models retrain, so the newest scars carry the value:

| | Fresh