kuma

# Kuma

Safety-first context & orchestration engine for AI coding agents.

Works with any MCP-compatible agent: Claude Code, Cursor, Windsurf, Zed, and more.

---

What is Kuma?

Kuma is an MCP (Model Context Protocol) server that acts as a pre-modification safety layer for AI coding agents. Before an agent touches your code, Kuma enforces a research and safety pipeline — like a pre-flight checklist for code changes.

The Problem: AI agents often modify code without understanding the full context — missing dependencies, breaking related features, or repeating past mistakes.

The Solution: Kuma is a shadow memory that injects "where is this file fragile and why is it written this way" right before the agent touches it:

• 🪄 Auto-inject hooks — gotchas/decisions/history injected before every edit, zero extra steps
• 🧠 Knowledge graph — SQLite-based derived cache (hash-verified, never stale)
• 📝 Decision memory — ADR-style decision tracking across sessions
• 📊 Kuma Studio — Visual dashboard for gotchas, decisions, and shadow-memory metrics

---

Quick Start

# Run with npx (zero setup)
npx -y @plumpslabs/kuma

# Or install globally
npm install -g @plumpslabs/kuma
kuma

Kuma auto-generates:

• .kuma/init.md — Project-specific behavioral rules
• .kuma/kuma.db — SQLite knowledge graph (WASM, zero native build)
• .skills/ — Skill files for common patterns

---

Core Architecture: 3 Pipeline-Driven Tools

Kuma provides 3 coarse-grained tools with impactful actions. Removed gimmick actions (add_node, feature, heal, harvest, session_mine, todo, context, benchmark, domain_rules, layers, noise_policy, lock, override, policy, contract, portability, doctor, gitignore, clean, progressive, sync, visualize, researches) are no longer documented.

🧠 kuma_context — Context & Research

Action	Purpose	Impact
init	Lean project brief + restore session	🔴 Required first
research	5-step pipeline: cache → graph → scan → impact → decision	🔴 Required before edits
history	Why is this file written this way (cross-session trace)	🔴 High
flow	Hash-verified derived flow cache (F13)	🔴 High
impact	Analyze change effects on related code	🟡 Linear
navigate	Trace code flow across files	🟡 Linear
changes	View change log for current session	🟡 Linear
rollback	Undo a specific change by ID	🟡 Linear
digest	Ultra-compact <500 token project briefing	🟡 Linear
drift	Detect memory staleness & code drift	🟡 Linear
resume	Load previous session context	🟡 Linear

💾 kuma_memory — Decision & Knowledge

Action	Purpose	Impact
gotcha	Record bugs/quirks IMMEDIATELY	🔴 Exponential
arch_flow	Record architecture flow (max 5 core files)	🔴 Exponential
decision	Record ADR-style decision with rationale	🔴 Exponential
research_save	Save research findings to cache	🟡 Linear
mine	Mine git history for hidden decisions	🟡 Linear
session	View session summary	🟢 Skip
search	Search knowledge graph	🟡 Linear
delete_node	Remove node/gotcha from graph + table	🟡 Linear
goal_progress	Track goal completion	🟢 Skip

🛡️ kuma_safety — Safety & Verification