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 exposes 3 coarse-grained tools with 13 core actions — the full agent surface. Anything else (impact, navigate, changes, digest, drift, resume, mine, session, delete_node, clear, goal_progress, check, audit, security, gc, ast, validate, gotcha_staleness) was removed — not hidden, gone — so the agent never has to choose from 30+ options and there is no dead surface to maintain.

🧠 kuma_context — Context & Research

💾 kuma_memory — Decision & Knowledge

🛡️ kuma_safety — Safety & Verification

Architecture

Kuma exposes exactly 3 coarse-grained tools — the agent picks an action, Kuma runs the internal workflow:

Everything else is an internal action — not exposed to the agent. The agent uses its own native tools for editing, searching, and execution — Kuma is memory & safety, not a code manager.

What Kuma Provides

• Knowledge Graph — SQLite + FTS5 full-text search (derived cache)
• Session Memory — track tool calls, recordings, and efficiency per session
• Guard System — real-time monitoring with blocking warnings for anti-patterns
• Shadow Injection — gotchas injected before edits via hooks (zero token waste when clean)
• Kuma Studio — visual dashboard with graph, gotchas, and injection metrics
• Checkpoint/Rollback — atomic snapshots before major refactors

Kuma Studio

Kuma Studio is a web-based dashboard for visualizing and managing your knowledge graph.

Features

• 📊 Knowledge Graph — Interactive node-edge visualization with physics simulation
• ⚠️ Gotchas — Known bugs and quirks with severity levels
• ⚡ Efficiency — Session metrics, time saved, verification pass rates
• 🪄 Injections — Shadow-memory metrics: injection count + time saved (24h)
• 📈 Staleness — Detection of stale nodes with missing file references

Usage

# Start Kuma Studio
kuma studio

# Or via npx
npx -y @plumpslabs/kuma studio

Studio runs at http://localhost:3322 and provides:

• Real-time graph visualization
• Copy report functionality for activity analysis
• Node detail modals with relations and gotchas
• Search and filter capabilities
• Physics-based graph layout with depth controls

Knowledge Graph Schema

Kuma builds a comprehensive knowledge graph with these node types:

Edge types include: contains, flows_through, owns, explains.

Safety Layer

Audit Trail

Every safety check is logged to the audit trail:

• Tool name and parameters
• Risk level (low/medium/high/critical)
• Allowed/blocked decision
• Duration and metadata

Workflow

A typical Kuma-powered session follows this flow:

1. INIT          → kuma_context({ action: 'init' })
                   Load project brief, restore session context

2. RESEARCH      → kuma_context({ action: 'research', scope: '<area>' })
                   5-step pipeline: cache → graph → impact → decision → safety

3. GUARD         → kuma_safety({ action: 'guard' })
                   Check for anti-patterns, drift, runaway loops

4. EDIT          → Agent modifies code (native tools)

5. RECORD        → kuma_memory({ action: 'gotcha' | 'arch_flow' | 'decision' })
                   Record what was learned for future sessions

6. VERIFY        → kuma_safety({ action: 'verify' })
                   Auto-run scoped tests + validation

7. CHECKPOINT    → kuma_safety({ action: 'checkpoint', label: 'post-<feature>' })
                   Snapshot once stable — restore with rollback_label if needed

Per-Project Context Model

Kuma stores all context locally in .kuma/:

.kuma/
├── kuma.db          # SQLite knowledge graph (WASM) — nodes, edges, research cache, changes
├── init.md          # Project behavioral rules (generated by `kuma init`)
├── memory.json      # Session state + metrics (auto)
├── auto-gotcha.json # Self-learning loop state (auto)
├── policy.yml       # OPTIONAL safety policy — only read if you create it
├── memories/        # Decision log markdown (decisions.md)
├── checkpoints/     # Atomic snapshots (label/ with kuma.db + files/)

Hooks are registered in .claude/settings.json (PreToolUse) — not stored under .kuma/.

Research cache is not a folder — it lives in the research_cache table inside kuma.db.

Key principle: Context is per-project, per-agent. No shared state between projects.

Why Kuma?

Installation

# Global install
npm install -g @plumpslabs/kuma

# Or use npx (no install needed)
npx -y @plumpslabs/kuma

# With pnpm
pnpm add -g @plumpslabs/kuma

Requirements

• Node.js >= 18.0.0
• No native dependencies (uses WASM for SQLite)

CLI Commands

# Start MCP server (default)
kuma

# Start Kuma Studio dashboard
kuma studio

# Initialize a project
kuma init

# Show version
kuma --version

# Show help
kuma --help

Configuration

MCP Client Configuration

Add to your MCP client config (e.g., Claude Desktop):

{
  "mcpServers": {
    "kuma": {
      "command": "npx",
      "args": ["-y", "@plumpslabs/kuma"]
    }
  }
}

Environment Variables

Development

# Clone the repo
git clone https://github.com/plumpslabs/kuma.git
cd kuma

# Install dependencies
pnpm install

# Build
pnpm run build:all

# Run tests
pnpm test

# Start studio in dev mode
pnpm run studio:dev

Power Curve: What to Record

License

MIT — use freely in personal and commercial projects.

Community

• GitHub: github.com/plumpslabs/kuma
• Issues: github.com/plumpslabs/kuma/issues
• npm: npm.im/@plumpslabs/kuma

_{Built with 🧠 by the Kuma community}