Kira

CI npm npm downloads scars absorbed License: MIT

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.

---

Install (10 seconds)

Add this snippet to your MCP host config:

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

That's it. Your agent now has Kira.

Per-client paths (click)

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).

---

The loop, in 30 seconds

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 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)

38 community skills across deploy / database / auth / payments / UI / testing / CI / infra / mobile / CMS, and 41 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.

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). 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).

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.

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 community feed	How
Contributor	✅ free	One accepted scar = 12 months (kira_share_scar → merge → key). First 1,000 contributors: permanent.
Supporter	✅ paid	Sponsor the project → supporter key. Funds human review of every submission.
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.

Currently in grace mode: the fresh feed is open to everyone until the corpus reaches 100 community scars. Full policy: RECIPROCITY.md.

---

Contributing

The first 1,000 contributors get permanent free access to all Kira features (fresh feed included) — see the reciprocity table above.

See CONTRIBUTING.md for how to add Skills and Scars.

---

Links

• npm
• The Flywheel — how the improvement loop runs
• Design Philosophy
• Business Plan
• Usage Guide
• Troubleshooting

---

Where agents shine — by remembering where they got burned.

A B Button Corporation project.