@plumpslabs/kuma 2.3.33 → 2.4.1

package/README.md

@@ -2,7 +2,7 @@
 <div align="center">
 
 <img src="https://raw.githubusercontent.com/plumpslabs/kuma/main/public/kuma.png" alt="Kuma Logo" width="180" />
-
+</div>
 # Kuma
 
 **Safety-first context & orchestration engine for AI coding agents.**
@@ -21,14 +21,11 @@ Kuma is an MCP (Model Context Protocol) server that acts as a **pre-modification
 
 **The Problem:** AI agents often modify code without understanding the full context — missing dependencies, breaking related features, or repeating past mistakes.
 
-**The Solution:** Kuma ensures every modification is informed by:
-- 🧠 **Project-specific knowledge graph** — SQLite-based graph of nodes, edges, gotchas, and decisions
-- 🔍 **Mandatory research pipeline** — 5-step context gathering before any edit
-- 🛡️ **Safety policies** — Configurable rules that block risky operations
+**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
-- 🔄 **Self-healing** — Automatic detection and repair of stale knowledge
-- ↩️ **Selective undo** — Symbol-level change tracking for precise reverts
-- 📊 **Kuma Studio** — Visual dashboard for knowledge graph, efficiency metrics, and activity tracking
+- 📊 **Kuma Studio** — Visual dashboard for gotchas, decisions, and shadow-memory metrics
 
 ---
 
@@ -46,101 +43,80 @@ kuma
 Kuma auto-generates:
 - `.kuma/init.md` — Project-specific behavioral rules
 - `.kuma/kuma.db` — SQLite knowledge graph (WASM, zero native build)
-- `.kuma/policy.yml` — Customizable safety policies
 - `.skills/` — Skill files for common patterns
 
 ---
 
 ## Core Architecture: 3 Pipeline-Driven Tools
 
-Kuma V3 consolidates 46+ micro-tools into **3 coarse-grained tools**. Each action triggers an internal multi-step workflow — the agent doesn't chain individual calls.
+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` | Load project brief, restore session | 🔴 Required first |
-| `research` | 5-step pipeline: cache → graph → impact → decision → safety | 🔴 Required before edits |
-| `impact` | Analyze change effects on related code | 🔴 High |
+| `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 |
-| `health` | Project health score (0-100) | 🟡 Linear |
 | `rollback` | Undo a specific change by ID | 🟡 Linear |
-| `sync` | Unified batch state query | 🟢 Skip (agent native) |
 | `digest` | Ultra-compact <500 token project briefing | 🟡 Linear |
 | `drift` | Detect memory staleness & code drift | 🟡 Linear |
-| `progressive` | Progressive context loading | 🟡 Linear |
+| `resume` | Load previous session context | 🟡 Linear |
 
 ### 💾 `kuma_memory` — Decision & Knowledge
 
 | Action | Purpose | Impact |
 |--------|---------|--------|
-| `research_save` | Save research findings to cache | 🔴 Exponential |
 | `gotcha` | Record bugs/quirks IMMEDIATELY | 🔴 Exponential |
 | `arch_flow` | Record architecture flow (max 5 core files) | 🔴 Exponential |
 | `decision` | Record ADR-style decision with rationale | 🔴 Exponential |
-| `feature` | Record high-level feature with owns edges | 🔴 Exponential |
+| `research_save` | Save research findings to cache | 🟡 Linear |
 | `mine` | Mine git history for hidden decisions | 🟡 Linear |
 | `session` | View session summary | 🟢 Skip |
-| `heal` | Repair stale graph entries | 🟡 Linear |
 | `search` | Search knowledge graph | 🟡 Linear |
-| `todo` | Manage persistent todos | 🟡 Linear |
-| `context` | Inject notes into context | 🟡 Linear |
-| `benchmark` | Capture/diff performance metrics | 🟡 Linear |
-| `domain_rules` | Layer 1: Business rules | 🟡 Linear |
-| `layers` | View all 3 memory layers | 🟢 Skip |
+| `delete_node` | Remove node/gotcha from graph + table | 🟡 Linear |
+| `goal_progress` | Track goal completion | 🟢 Skip |
 
-### 🛡️ `kuma_safety` — Safety & Policy
+### 🛡️ `kuma_safety` — Safety & Verification
 
 | Action | Purpose | Impact |
 |--------|---------|--------|
 | `guard` | Detect anti-patterns, drift, runaway loops | 🔴 Required |
-| `verify` | Auto-run scoped tests + AST validation | 🔴 High |
+| `verify` | Auto-run scoped tests after edits | 🔴 High |
 | `check` | Pre-execution safety check | 🟡 Linear |
 | `audit` | Query safety audit trail | 🟡 Linear |
-| `lock` | Multi-agent coordination lock | 🟡 Linear |
-| `health` | Safety health score | 🟡 Linear |
-| `override` | Bypass safety (recorded in audit) | 🟡 Linear |
-| `security` | Scan for leaked secrets | 🟡 Linear |
+| `security` | Scan for leaked secrets/tokens | 🟡 Linear |
 | `gc` | Garbage collect stale data | 🟢 Skip |
-| `doctor` | Full health check | 🟡 Linear |
-| `policy` | Policy-as-Code engine | 🟡 Linear |
 | `ast` / `validate` | AST-based code validation | 🟡 Linear |
 | `checkpoint` | Atomic snapshot before refactors | 🟡 Linear |
 | `rollback_label` | Restore from checkpoint | 🟡 Linear |
-| `contract` | Pre/post-condition checks | 🟡 Linear |
 
 ---
 
-## V3 Changes: What's New
+## Architecture
 
-Kuma V3 is a major evolution focusing on **simplicity, safety, and agent-native workflows**.
+Kuma exposes exactly **3 coarse-grained tools** — the agent picks an *action*, Kuma runs the internal workflow:
 
-### Dropped Tools (Now Handled by Agents)
+| Tool | Core Actions | Purpose |
+|------|--------------|---------|
+| `kuma_context` | `init`, `research`, `history` | Load project context, understand unfamiliar code |
+| `kuma_memory` | `gotcha`, `decision`, `arch_flow`, `research_save` | Persistent knowledge that saves future sessions |
+| `kuma_safety` | `guard`, `verify` | Pre-risk check, post-edit verification |
 
-| Dropped Tool | Why Dropped |
-|--------------|-------------|
-| `precise_diff_editor` | Agent has native edit tools |
-| `safe_terminal_exec` | Agent executes commands natively |
-| `smart_grep` | Agent searches natively (ripgrep, semantic) |
-| `batch_file_writer` | Agent creates files natively |
-| `ast_validator` (standalone) | Merged into `kuma_safety` as `ast`/`validate` action |
-| `git_diff_analyzer` | Merged into `kuma_context` as `impact` action |
+Everything else is an internal action for power users. The agent uses its **own native tools** for editing, searching, and execution — Kuma is memory & safety, not a code manager.
 
-### New Features in V3
+### What Kuma Provides
 
-| Feature | Description |
-|---------|-------------|
-| **3 Coarse-Grained Tools** | Simplified API: `kuma_context`, `kuma_memory`, `kuma_safety` |
-| **Pipeline-Driven Actions** | Each action triggers internal multi-step workflows |
-| **Knowledge Graph** | SQLite + FTS5 full-text search with WASM engine |
-| **Feature Recording** | Auto-detect and record high-level features with `owns` edges |
-| **Session Memory** | Track tool calls, recordings, and efficiency per session |
-| **Guard System** | Real-time monitoring with blocking warnings for anti-patterns |
-| **Self-Healing** | Automatic detection and repair of stale nodes |
-| **Kuma Studio** | Visual dashboard with graph, efficiency, and activity tracking |
-| **Policy-as-Code** | Configurable safety rules in `.kuma/policy.yml` |
-| **Checkpoint/Rollback** | Atomic snapshots before major refactors |
+- **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
 
 ---
 
@@ -151,12 +127,10 @@ Kuma Studio is a **web-based dashboard** for visualizing and managing your knowl
 ### Features
 
 - **📊 Knowledge Graph** — Interactive node-edge visualization with physics simulation
-- **⭐ Features** — High-level module tracking with owns edges to files
 - **⚠️ Gotchas** — Known bugs and quirks with severity levels
-- **💚 Health** — Project health scores over time
 - **⚡ 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
-- **🤖 Activity** — Agent usage intensity, success rates, and session history
 
 ### Usage
 
@@ -195,47 +169,20 @@ Kuma builds a comprehensive knowledge graph with these node types:
 | `test` | Test file |
 | `research` | Research cache entry |
 
-Edge types include: `calls`, `imports`, `defines`, `tests`, `routes`, `implements`, `extends`, `depends_on`, `owns`, `modified_by`, `contains`, `composes`, `flows_through`, `triggers`, `syncs_with`, `affects`.
+Edge types include: `contains`, `flows_through`, `owns`, `explains`.
 
 ---
 
 ## Safety Layer
 
-### Policy Engine
-
-Configure safety rules in `.kuma/policy.yml`:
-
-```yaml
-rules:
-  - name: "No production databases"
-    pattern: "DROP TABLE|DELETE FROM.*WHERE 1"
-    action: block
-    message: "Production database modifications blocked"
-    
-  - name: "Require tests before deploy"
-    pattern: "git push"
-    require: "kuma_safety({ action: 'verify' })"
-    message: "Run tests before pushing"
-```
-
 ### Audit Trail
 
 Every safety check is logged to the audit trail:
 - Tool name and parameters
 - Risk level (low/medium/high/critical)
-- Policy violations
 - Allowed/blocked decision
 - Duration and metadata
 
-### Multi-Agent Lock
-
-Prevent conflicts when multiple agents work on the same project:
-```bash
-kuma_safety({ action: 'lock', acquire: true })
-# ... work ...
-kuma_safety({ action: 'lock', release: true })
-```
-
 ---
 
 ## Workflow
@@ -272,15 +219,20 @@ Kuma stores all context locally in `.kuma/`:
 
 ```
 .kuma/
-├── kuma.db          # SQLite knowledge graph (WASM)
-├── init.md          # Project-specific behavioral rules
-├── policy.yml       # Safety policies
-├── memory.json      # Session metrics and recordings
-├── research/        # Research cache files
-├── memories/        # Memory layer files (domain_rules, arch_flow, gotcha)
-└── checkpoints/     # Atomic snapshots for rollback
+├── 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/        # Memory layer markdown (decisions.md, arch_flow.md, ...)
+├── checkpoints/     # Atomic snapshots (label/ with kuma.db + files/)
+└── scratch/         # Temp debug artifacts (auto, ephemeral)
 ```
 
+> 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.
 
 ---
@@ -292,10 +244,10 @@ Kuma stores all context locally in `.kuma/`:
 | **Context** | Agent forgets project-specific patterns | Knowledge graph persists across sessions |
 | **Safety** | Agent may break critical code | Policy engine blocks risky operations |
 | **Impact** | Agent doesn't know what's affected | Impact analysis traces dependencies |
-| **Coordination** | Multiple agents conflict | Multi-agent lock prevents collisions |
+| **Coordination** | Multiple agents conflict | Per-agent session state + audit trail avoid collisions |
 | **Memory** | Agent repeats past mistakes | Decision memory + gotchas prevent loops |
-| **Reversibility** | Hard to undo changes | Selective undo at symbol level |
-| **Staleness** | Knowledge becomes outdated | Self-healing detects and repairs stale data |
+| **Reversibility** | Hard to undo changes | Checkpoint snapshots + selective undo |
+| **Staleness** | Knowledge becomes outdated | Drift detection + gotcha staleness checks flag stale data |
 
 ---