{
  "markdown": "# Kira\n\n[![CI](https://github.com/aibenyclaude-coder/Kira/actions/workflows/ci.yml/badge.svg)](https://github.com/aibenyclaude-coder/Kira/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/kira-mcp.svg)](https://www.npmjs.com/package/kira-mcp)\n[![npm downloads](https://img.shields.io/npm/dw/kira-mcp.svg)](https://www.npmjs.com/package/kira-mcp)\n[![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/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n\n### Your agent stops repeating its own mistakes.\n\nEvery 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.\n\n> **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).\n\n---\n\n## Install (10 seconds)\n\nAdd this snippet to your MCP host config:\n\n```json\n{\n  \"mcpServers\": {\n    \"kira\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"kira-mcp@latest\"]\n    }\n  }\n}\n```\n\nThat's it. Your agent now has Kira.\n\n<details>\n<summary><b>Per-client paths (click)</b></summary>\n\n| Client | Config file |\n|---|---|\n| **Claude Code** | `~/.claude/settings.json` (global) or `.claude/settings.json` (per-project) |\n| **Claude Desktop** | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project) |\n| **Cline / Continue** | extension settings → MCP servers |\n| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |\n| **VS Code (MCP preview)** | `.vscode/mcp.json` |\n| **Goose** | `~/.config/goose/profiles.yaml` (under `extensions:`) |\n| **Zed** | `~/.config/zed/settings.json` (`context_servers`) |\n\nThe snippet above works as-is in every one of them — just paste it under `mcpServers` (or the equivalent key for your client).\n</details>\n\n---\n\n## The loop, in 30 seconds\n\n```text\nMonday    agent gates a merge on:  npm run build 2>&1 | tail -1\n          exit code comes from tail, not the compiler → broken code reaches main\n          └─ kira_record_failure(\n               title:   \"build gate bypassed: exit code swallowed by pipe to tail\",\n               instead: \"never gate on a piped command without pipefail\")\n\nTuesday   new session, same machine\n          └─ session brief: \"⚠ You have been burned by this before:\n             never gate on a piped command without set -o pipefail\"\n          agent writes the gate correctly. Zero repeats. Zero wasted tokens.\n```\n\nNot 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.\n\n---\n\n## Tools (10)\n\n| | Tool | What it does |\n|---|------|-------------|\n| **Personal memory** | `kira_record_failure` | Capture a retry/exception as a personal scar (local-only) |\n| | `kira_personal_brief` | Session-start brief of your latest scars — start work already knowing where you got burned |\n| | `kira_premortem` | Failure heat-map for a goal *before* starting — \"here's where this kind of task has burned you\" |\n| **Catalog** | `kira_lookup` | Keyword → proven instructions + failure warnings. On a miss, returns scored `near_skills` / `near_scars` instead of a shrug |\n| | `kira_get` | Fetch full step-by-step instructions by ID |\n| | `kira_route` | Goal → ordered plan with a skill per step |\n| **Community** | `kira_share_scar` | Promote a personal scar into a community submission (sanitized; nothing uploads without your click) — earns contributor status |\n| **Feedback** | `kira_report` | Report success/retry/failure → feeds the quality loop |\n| | `kira_consent` / `kira_status` | Telemetry consent + one-call introspection |\n\n**Auto-firing:** you don't call Kira — Kira's MCP instructions tell your agent when to. Japanese queries are first-class (CJK bigram matching).\n\n### When nothing matches\n\nA 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.\n\n---\n\n## The catalog layer (community skills & scars)\n\n![Kira Demo](./demo.gif)\n\n38 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.\n\n**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).\n\nEvery accepted scar earns **contributor status** — sharing is how you get the fresh feed for free (see Contributing below).\n\n---\n\n## How it works\n\n```\nYour agent hits a wall            Your agent gets a task\n    ↓                                 ↓\nkira_record_failure()             kira_premortem(goal) / kira_lookup(keyword)\n    ↓                                 ↓\n~/.kira/personal-scars/           scars first, then instructions\n    ↓                                 ↓\nnext session: brief surfaces      agent announces → executes → kira_report()\nyour scars before work starts         ↓\n    ↓                             misses + failure notes feed the flywheel\nnever the same mistake twice      → digest → catalog improvements\n```\n\nSkills are natural language Markdown — no executable code, no injection risk.\n\n---\n\n## Why not just CLAUDE.md?\n\n| | CLAUDE.md / .cursorrules | Kira |\n|---|---|---|\n| Setup | Copy per project | Install once |\n| Failure memory | You write it by hand, if you remember | `kira_record_failure` — captured at the moment it happens |\n| Recall | You re-read it, if you remember | Surfaced automatically at session start / task start |\n| Selection | You choose | Agent chooses, scored |\n| Updates | Manual | Automatic (flywheel) |\n| Works across AI tools | Tool-specific | Any MCP client |\n\n## Not another \"memory MCP\"?\n\nThere are excellent memory servers (knowledge graphs, session recall, context handoff). Kira is deliberately narrower:\n\n- **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.\n- **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.\n- **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.\n- **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)).\n\nIf you need general episodic memory, run one of those servers *alongside* Kira — they don't compete for the same job.\n\n---\n\n## Telemetry\n\nPersonal scars (`~/.kira/personal-scars/`) and the miss log (`~/.kira/misses.log`) are **local-only and never uploaded**. Community telemetry is separate and consent-gated:\n\n| Mode (`KIRA_TELEMETRY` env, or `kira_consent` MCP tool) | What leaves your machine |\n|---|---|\n| `off` | Nothing. Local log only. |\n| `basic` *(default)* | Anonymous core: skill ID, status, anonymous UUID, kira version, OS family, Node major version, free/pro tier. **No free text.** |\n| `full` | Same as basic plus **sanitized** `note` / `context` (secrets, paths, identifiers redacted). |\n\nFull schema, redaction rules, retention, and opt-out instructions: **[PRIVACY.md](./PRIVACY.md)**.\n\n| Env var | Default | Purpose |\n|---|---|---|\n| `KIRA_TELEMETRY` | (unset → `basic`) | Override consent level for this process: `off`, `basic`, `full`. |\n| `KIRA_TELEMETRY_URL` | `https://kira-telemetry.workers.dev/v1/reports` | Endpoint for batch upload. |\n| `KIRA_HOME` | `~/.kira` | Where consent state, personal scars, miss log, and flywheel output live. |\n| `KIRA_KEY` | (unset → free tier) | Contributor / supporter key — unlocks the fresh community feed. |\n| `KIRA_REMOTE_URL` | (unset → no network) | Opt-in corpus feed URL for the free tier (90-day-delayed commons). |\n\n---\n\n## Share a scar, or subscribe, or wait\n\nThe 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:\n\n| | Fresh community feed | How |\n|---|---|---|\n| **Contributor** | ✅ free | One accepted scar = 12 months (`kira_share_scar` → merge → key). **First 1,000 contributors: permanent.** |\n| **Supporter** | ✅ paid | Sponsor the project → supporter key. Funds human review of every submission. |\n| **Free** | 90 days later | Base corpus ships with npm; delayed commons feed available opt-in. Local features + privacy guarantees are free forever, on every tier. |\n\nCurrently in **grace mode**: the fresh feed is open to everyone until the corpus reaches 100 community scars. Full policy: [RECIPROCITY.md](./RECIPROCITY.md).\n\n---\n\n## Contributing\n\nThe first **1,000 contributors** get permanent free access to all Kira features (fresh feed included) — see the reciprocity table above.\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for how to add Skills and Scars.\n\n---\n\n## Links\n\n- [npm](https://www.npmjs.com/package/kira-mcp)\n- [The Flywheel](./FLYWHEEL.md) — how the improvement loop runs\n- [Design Philosophy](./DESIGN.md)\n- [Business Plan](./PLAN.md)\n- [Usage Guide](./USAGE.md)\n- [Troubleshooting](./TROUBLESHOOTING.md)\n\n---\n\n**Where agents shine — by remembering where they got burned.**\n\n*A [B Button Corporation](https://github.com/aibenyclaude-coder) project.*\n",
  "bytes": 11250,
  "sha": "a30f9d74ddb174f8c06958e5cf9384f3d1fb27dd9fd0153fc98e5a0757b9d2a7",
  "repo_slug": "aibenyclaude-coder/kira",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aibenyclaude_coder_kira_e5579ca2/readme"
}