@plumpslabs/kuma 2.3.32 → 2.3.34
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +284 -188
- package/dist/index.js +4003 -6202
- package/package.json +1 -1
- package/packages/ide/studio/dist/index.js +54 -22
- package/packages/ide/studio/public/index.html +370 -90
package/README.md
CHANGED
|
@@ -1,286 +1,382 @@
|
|
|
1
|
+
|
|
1
2
|
<div align="center">
|
|
2
3
|
|
|
3
4
|
<img src="https://raw.githubusercontent.com/plumpslabs/kuma/main/public/kuma.png" alt="Kuma Logo" width="180" />
|
|
4
|
-
|
|
5
|
+
</div>
|
|
5
6
|
# Kuma
|
|
6
7
|
|
|
7
|
-
**Safety-first context & orchestration engine for AI coding agents
|
|
8
|
+
**Safety-first context & orchestration engine for AI coding agents.**
|
|
8
9
|
|
|
9
|
-
[](https://npm.im/@plumpslabs/kuma)
|
|
11
|
+
[](LICENSE)
|
|
12
|
+
[](https://nodejs.org)
|
|
12
13
|
|
|
13
|
-
Works with
|
|
14
|
-
|
|
15
|
-
</div>
|
|
14
|
+
> Works with any MCP-compatible agent: Claude Code, Cursor, Windsurf, Zed, and more.
|
|
16
15
|
|
|
17
16
|
---
|
|
18
17
|
|
|
19
18
|
## What is Kuma?
|
|
20
19
|
|
|
21
|
-
Kuma is an
|
|
20
|
+
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.
|
|
22
21
|
|
|
23
|
-
|
|
22
|
+
**The Problem:** AI agents often modify code without understanding the full context — missing dependencies, breaking related features, or repeating past mistakes.
|
|
24
23
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
24
|
+
**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:
|
|
25
|
+
- 🪄 **Auto-inject hooks** — gotchas/decisions/history injected before every edit, zero extra steps
|
|
26
|
+
- 🧠 **Knowledge graph** — SQLite-based derived cache (hash-verified, never stale)
|
|
27
|
+
- 📝 **Decision memory** — ADR-style decision tracking across sessions
|
|
28
|
+
- 📊 **Kuma Studio** — Visual dashboard for gotchas, decisions, and shadow-memory metrics
|
|
28
29
|
|
|
29
30
|
---
|
|
30
31
|
|
|
31
|
-
##
|
|
32
|
-
|
|
33
|
-
**Yes — to run Kuma, you need exactly zero configuration:**
|
|
32
|
+
## Quick Start
|
|
34
33
|
|
|
35
34
|
```bash
|
|
35
|
+
# Run with npx (zero setup)
|
|
36
36
|
npx -y @plumpslabs/kuma
|
|
37
|
-
```
|
|
38
37
|
|
|
39
|
-
|
|
38
|
+
# Or install globally
|
|
39
|
+
npm install -g @plumpslabs/kuma
|
|
40
|
+
kuma
|
|
41
|
+
```
|
|
40
42
|
|
|
41
|
-
|
|
43
|
+
Kuma auto-generates:
|
|
44
|
+
- `.kuma/init.md` — Project-specific behavioral rules
|
|
45
|
+
- `.kuma/kuma.db` — SQLite knowledge graph (WASM, zero native build)
|
|
46
|
+
- `.skills/` — Skill files for common patterns
|
|
42
47
|
|
|
43
48
|
---
|
|
44
49
|
|
|
45
|
-
## Core
|
|
50
|
+
## Core Architecture: 3 Pipeline-Driven Tools
|
|
46
51
|
|
|
47
|
-
|
|
52
|
+
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.
|
|
48
53
|
|
|
49
|
-
|
|
54
|
+
### 🧠 `kuma_context` — Context & Research
|
|
55
|
+
|
|
56
|
+
| Action | Purpose | Impact |
|
|
57
|
+
|--------|---------|--------|
|
|
58
|
+
| `init` | Lean project brief + restore session | 🔴 Required first |
|
|
59
|
+
| `research` | 5-step pipeline: cache → graph → scan → impact → decision | 🔴 Required before edits |
|
|
60
|
+
| `history` | Why is this file written this way (cross-session trace) | 🔴 High |
|
|
61
|
+
| `flow` | Hash-verified derived flow cache (F13) | 🔴 High |
|
|
62
|
+
| `impact` | Analyze change effects on related code | 🟡 Linear |
|
|
63
|
+
| `navigate` | Trace code flow across files | 🟡 Linear |
|
|
64
|
+
| `changes` | View change log for current session | 🟡 Linear |
|
|
65
|
+
| `rollback` | Undo a specific change by ID | 🟡 Linear |
|
|
66
|
+
| `digest` | Ultra-compact <500 token project briefing | 🟡 Linear |
|
|
67
|
+
| `drift` | Detect memory staleness & code drift | 🟡 Linear |
|
|
68
|
+
| `resume` | Load previous session context | 🟡 Linear |
|
|
69
|
+
|
|
70
|
+
### 💾 `kuma_memory` — Decision & Knowledge
|
|
71
|
+
|
|
72
|
+
| Action | Purpose | Impact |
|
|
73
|
+
|--------|---------|--------|
|
|
74
|
+
| `gotcha` | Record bugs/quirks IMMEDIATELY | 🔴 Exponential |
|
|
75
|
+
| `arch_flow` | Record architecture flow (max 5 core files) | 🔴 Exponential |
|
|
76
|
+
| `decision` | Record ADR-style decision with rationale | 🔴 Exponential |
|
|
77
|
+
| `research_save` | Save research findings to cache | 🟡 Linear |
|
|
78
|
+
| `mine` | Mine git history for hidden decisions | 🟡 Linear |
|
|
79
|
+
| `session` | View session summary | 🟢 Skip |
|
|
80
|
+
| `search` | Search knowledge graph | 🟡 Linear |
|
|
81
|
+
| `delete_node` | Remove node/gotcha from graph + table | 🟡 Linear |
|
|
82
|
+
| `goal_progress` | Track goal completion | 🟢 Skip |
|
|
83
|
+
|
|
84
|
+
### 🛡️ `kuma_safety` — Safety & Verification
|
|
85
|
+
|
|
86
|
+
| Action | Purpose | Impact |
|
|
87
|
+
|--------|---------|--------|
|
|
88
|
+
| `guard` | Detect anti-patterns, drift, runaway loops | 🔴 Required |
|
|
89
|
+
| `verify` | Auto-run scoped tests after edits | 🔴 High |
|
|
90
|
+
| `check` | Pre-execution safety check | 🟡 Linear |
|
|
91
|
+
| `audit` | Query safety audit trail | 🟡 Linear |
|
|
92
|
+
| `health` | Project health score (optional/cosmetic) | 🟢 Skip |
|
|
93
|
+
| `security` | Scan for leaked secrets/tokens | 🟡 Linear |
|
|
94
|
+
| `gc` | Garbage collect stale data | 🟢 Skip |
|
|
95
|
+
| `ast` / `validate` | AST-based code validation | 🟡 Linear |
|
|
96
|
+
| `checkpoint` | Atomic snapshot before refactors | 🟡 Linear |
|
|
97
|
+
| `rollback_label` | Restore from checkpoint | 🟡 Linear |
|
|
50
98
|
|
|
51
|
-
|
|
52
|
-
- Auto-built, auto-healed, queryable
|
|
53
|
-
- Per-project — your context stays with your codebase
|
|
99
|
+
---
|
|
54
100
|
|
|
55
|
-
|
|
101
|
+
## V3 Changes: What's New
|
|
56
102
|
|
|
57
|
-
|
|
103
|
+
Kuma V3 is a major evolution focusing on **simplicity, safety, and agent-native workflows**.
|
|
58
104
|
|
|
59
|
-
|
|
60
|
-
|------|-------------|
|
|
61
|
-
| **1. Load Cache** | Check `.kuma/research/<scope>.json` — fresh or stale? |
|
|
62
|
-
| **2. Graph Query** | Find all related nodes and edges in the knowledge graph |
|
|
63
|
-
| **3. Impact Analysis** | "If I change X, what breaks?" — references, files, tests, API routes |
|
|
64
|
-
| **4. Decision Lookup** | Check past ADR-style decisions and known issues |
|
|
65
|
-
| **5. Safety Check** | Policy compliance, active locks, risk level |
|
|
105
|
+
### Dropped Tools (Now Handled by Agents)
|
|
66
106
|
|
|
67
|
-
|
|
107
|
+
| Dropped Tool | Why Dropped |
|
|
108
|
+
|--------------|-------------|
|
|
109
|
+
| `precise_diff_editor` | Agent has native edit tools |
|
|
110
|
+
| `safe_terminal_exec` | Agent executes commands natively |
|
|
111
|
+
| `smart_grep` | Agent searches natively (ripgrep, semantic) |
|
|
112
|
+
| `batch_file_writer` | Agent creates files natively |
|
|
113
|
+
| `ast_validator` (standalone) | Merged into `kuma_safety` as `ast`/`validate` action |
|
|
114
|
+
| `git_diff_analyzer` | Merged into `kuma_context` as `impact` action |
|
|
68
115
|
|
|
69
|
-
###
|
|
116
|
+
### New Features in V3
|
|
70
117
|
|
|
71
|
-
| Feature |
|
|
118
|
+
| Feature | Description |
|
|
72
119
|
|---------|-------------|
|
|
73
|
-
| **
|
|
74
|
-
| **
|
|
75
|
-
| **
|
|
76
|
-
| **
|
|
120
|
+
| **3 Coarse-Grained Tools** | Simplified API: `kuma_context`, `kuma_memory`, `kuma_safety` |
|
|
121
|
+
| **Pipeline-Driven Actions** | Each action triggers internal multi-step workflows |
|
|
122
|
+
| **Knowledge Graph** | SQLite + FTS5 full-text search with WASM engine (derived cache) |
|
|
123
|
+
| **Session Memory** | Track tool calls, recordings, and efficiency per session |
|
|
124
|
+
| **Guard System** | Real-time monitoring with blocking warnings for anti-patterns |
|
|
125
|
+
| **Kuma Studio** | Visual dashboard with graph, gotchas, and injection metrics |
|
|
126
|
+
| **Checkpoint/Rollback** | Atomic snapshots before major refactors |
|
|
127
|
+
|
|
128
|
+
---
|
|
77
129
|
|
|
78
|
-
|
|
130
|
+
## Kuma Studio
|
|
79
131
|
|
|
80
|
-
|
|
132
|
+
Kuma Studio is a **web-based dashboard** for visualizing and managing your knowledge graph.
|
|
81
133
|
|
|
134
|
+
### Features
|
|
135
|
+
|
|
136
|
+
- **📊 Knowledge Graph** — Interactive node-edge visualization with physics simulation
|
|
137
|
+
- **⚠️ Gotchas** — Known bugs and quirks with severity levels
|
|
138
|
+
- **⚡ Efficiency** — Session metrics, time saved, verification pass rates
|
|
139
|
+
- **🪄 Injections** — Shadow-memory metrics: injection count + time saved (24h)
|
|
140
|
+
- **📈 Staleness** — Detection of stale nodes with missing file references
|
|
141
|
+
|
|
142
|
+
### Usage
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
# Start Kuma Studio
|
|
146
|
+
kuma studio
|
|
147
|
+
|
|
148
|
+
# Or via npx
|
|
149
|
+
npx -y @plumpslabs/kuma studio
|
|
82
150
|
```
|
|
83
|
-
Context: "We need stateless tokens that expire in 15min"
|
|
84
|
-
Options: "JWT vs opaque tokens vs session store"
|
|
85
|
-
Rationale: "JWT is mobile-compatible, no server-side store needed"
|
|
86
|
-
Outcome: "Implemented JwtPasswordResetService"
|
|
87
|
-
```
|
|
88
151
|
|
|
89
|
-
|
|
152
|
+
Studio runs at `http://localhost:3322` and provides:
|
|
153
|
+
- Real-time graph visualization
|
|
154
|
+
- Copy report functionality for activity analysis
|
|
155
|
+
- Node detail modals with relations and gotchas
|
|
156
|
+
- Search and filter capabilities
|
|
157
|
+
- Physics-based graph layout with depth controls
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Knowledge Graph Schema
|
|
162
|
+
|
|
163
|
+
Kuma builds a comprehensive knowledge graph with these node types:
|
|
164
|
+
|
|
165
|
+
| Node Type | Description |
|
|
166
|
+
|-----------|-------------|
|
|
167
|
+
| `feature` | High-level module (e.g., Auth, Billing) |
|
|
168
|
+
| `arch_flow` | Architecture flow between files |
|
|
169
|
+
| `gotcha` | Known bug or quirk |
|
|
170
|
+
| `decision` | ADR-style decision with rationale |
|
|
171
|
+
| `function` | Function or method |
|
|
172
|
+
| `class` | Class definition |
|
|
173
|
+
| `component` | UI component |
|
|
174
|
+
| `file` | Source file |
|
|
175
|
+
| `api_route` | API endpoint |
|
|
176
|
+
| `test` | Test file |
|
|
177
|
+
| `research` | Research cache entry |
|
|
90
178
|
|
|
91
|
-
|
|
179
|
+
Edge types include: `contains`, `flows_through`, `owns`, `explains`.
|
|
92
180
|
|
|
93
|
-
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## Safety Layer
|
|
184
|
+
|
|
185
|
+
### Audit Trail
|
|
186
|
+
|
|
187
|
+
Every safety check is logged to the audit trail:
|
|
188
|
+
- Tool name and parameters
|
|
189
|
+
- Risk level (low/medium/high/critical)
|
|
190
|
+
- Allowed/blocked decision
|
|
191
|
+
- Duration and metadata
|
|
94
192
|
|
|
95
|
-
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## Workflow
|
|
96
196
|
|
|
97
|
-
|
|
197
|
+
A typical Kuma-powered session follows this flow:
|
|
98
198
|
|
|
99
199
|
```
|
|
100
|
-
kuma_context({ action:
|
|
200
|
+
1. INIT → kuma_context({ action: 'init' })
|
|
201
|
+
Load project brief, restore session context
|
|
202
|
+
|
|
203
|
+
2. RESEARCH → kuma_context({ action: 'research', scope: '<area>' })
|
|
204
|
+
5-step pipeline: cache → graph → impact → decision → safety
|
|
205
|
+
|
|
206
|
+
3. GUARD → kuma_safety({ action: 'guard' })
|
|
207
|
+
Check for anti-patterns, drift, runaway loops
|
|
208
|
+
|
|
209
|
+
4. EDIT → Agent modifies code (native tools)
|
|
210
|
+
|
|
211
|
+
5. RECORD → kuma_memory({ action: 'gotcha' | 'arch_flow' | 'decision' })
|
|
212
|
+
Record what was learned for future sessions
|
|
213
|
+
|
|
214
|
+
6. VERIFY → kuma_safety({ action: 'verify' })
|
|
215
|
+
Auto-run scoped tests + AST validation
|
|
216
|
+
|
|
217
|
+
7. REVIEW → kuma_context({ action: 'changes' })
|
|
218
|
+
Review what was modified this session
|
|
101
219
|
```
|
|
102
220
|
|
|
103
221
|
---
|
|
104
222
|
|
|
105
|
-
##
|
|
223
|
+
## Per-Project Context Model
|
|
106
224
|
|
|
107
|
-
Kuma
|
|
225
|
+
Kuma stores all context locally in `.kuma/`:
|
|
108
226
|
|
|
109
|
-
|
|
227
|
+
```
|
|
228
|
+
.kuma/
|
|
229
|
+
├── kuma.db # SQLite knowledge graph (WASM) — nodes, edges, research cache, changes
|
|
230
|
+
├── init.md # Project behavioral rules (generated by `kuma init`)
|
|
231
|
+
├── memory.json # Session state + metrics (auto)
|
|
232
|
+
├── auto-gotcha.json # Self-learning loop state (auto)
|
|
233
|
+
├── policy.yml # OPTIONAL safety policy — only read if you create it
|
|
234
|
+
├── memories/ # Memory layer markdown (decisions.md, arch_flow.md, ...)
|
|
235
|
+
├── checkpoints/ # Atomic snapshots (label/ with kuma.db + files/)
|
|
236
|
+
└── scratch/ # Temp debug artifacts (auto, ephemeral)
|
|
237
|
+
```
|
|
110
238
|
|
|
111
|
-
|
|
112
|
-
|--------|----------|----------|
|
|
113
|
-
| `init` | Project brief | **Call first every session.** Load graph, detect stack, show structure. |
|
|
114
|
-
| `research` | 5-step pipeline | **WAJIB before editing.** Cache → staleness → graph → impact → decisions. |
|
|
115
|
-
| `impact` | Graph traversal | "Change validateToken → 42 refs, 15 files, 3 tests, 2 API routes." |
|
|
116
|
-
| `navigate` | BFS traversal | "How does login work?" — full call chain from route to database. |
|
|
117
|
-
| `changes` | Change log query | "What changed this session?" — selective undo support. |
|
|
118
|
-
| `health` | Aggregate scoring | Project health dashboard 0-100 across 9 dimensions. |
|
|
119
|
-
| `rollback` | File restore | Rollback a specific change by ID from the change log. |
|
|
120
|
-
| `researches` | Cache list | List all cached research scopes with confidence & age. |
|
|
121
|
-
| `sync` | Unified batch | Combines init + health + memory state in single roundtrip (~60-70% token savings). |
|
|
122
|
-
| `visualize` | Mermaid diagram | Generate interactive knowledge graph diagrams (flowchart, dependency, mindmap). |
|
|
123
|
-
| `digest` | Ultra-compact brief | <500 token project briefing — fastest way to bootstrap context (Issue #18). |
|
|
124
|
-
| `drift` | Staleness detection | Detect memory staleness & code drift between graph and actual filesystem (Issue #20). |
|
|
125
|
-
|
|
126
|
-
### 📝 `kuma_memory` — Decision & Knowledge
|
|
127
|
-
|
|
128
|
-
| Action | Use case |
|
|
129
|
-
|--------|----------|
|
|
130
|
-
| `decision` | ADR-style recording: template, suggest, or record. |
|
|
131
|
-
| `mine` | Mine historical decisions from git log & inline code comments. |
|
|
132
|
-
| `research_save` | Persist research to graph + `.kuma/research/<scope>.json`. |
|
|
133
|
-
| `session` | "What happened this session?" — files, failures, progress. |
|
|
134
|
-
| `heal` | Self-heal knowledge graph — stale detection, git repair. |
|
|
135
|
-
| `search` | Search across memories + knowledge graph (with TF-IDF hybrid semantic search). |
|
|
136
|
-
| `changes` | Change log for selective undo. |
|
|
137
|
-
| `todo` | Persistent todo CRUD — add, list, update status with scope & success criteria. |
|
|
138
|
-
| `context` | Inject context notes from external sources (Slack, Jira, meetings). |
|
|
139
|
-
| `benchmark` | Before/after metric capture & diff (e.g., type errors, test count). |
|
|
140
|
-
| `decision_log` | Living decision document with status tracking (active/superseded/deprecated). |
|
|
141
|
-
| `domain_rules` | Layer 1 — Business/domain rules knowledge (Issue #17). |
|
|
142
|
-
| `arch_flow` | Layer 2 — Architecture flow mapping (Issue #17). |
|
|
143
|
-
| `gotcha` | Layer 3 — Known gotchas & anti-regression shield (Issue #17/#21). |
|
|
144
|
-
| `layers` | Show all 3 memory layers summary. |
|
|
145
|
-
| `delete_node` | Delete specific node or record from disk & RAM immediately. |
|
|
146
|
-
| `graph_health` | Monitor knowledge graph health, orphan nodes, and duplicate groups. |
|
|
147
|
-
|
|
148
|
-
### 🛡️ `kuma_safety` — Safety & Policy
|
|
149
|
-
|
|
150
|
-
| Action | Use case |
|
|
151
|
-
|--------|----------|
|
|
152
|
-
| `guard` | Anti-pattern, drift, tool-loop, and failure checks. |
|
|
153
|
-
| `verify` | **SAFETY-GUARDED** on-demand test verification — only runs via explicit tool call. Auto-detects runner (pnpm/npm/yarn/pytest/cargo/go), scopes to session changes, rate-limited (30s handler + 60s verifier cooldown), concurrency-locked (intra-process + cross-process file lock), cached (< 5 min returns stale result), runaway-protected (> 3 calls in 5 min auto-blocks), hard timeout (30s + SIGKILL). ⚠️ NEVER auto-triggered — only via explicit `kuma_safety({ action: "verify" })`. |
|
|
154
|
-
| `check` | Pre-execution safety: policy, path, lock, risk level. |
|
|
155
|
-
| `audit` | Query audit trail + stats + override log. |
|
|
156
|
-
| `lock` | Multi-agent file locking. |
|
|
157
|
-
| `health` | Safety score 0-100 with dimension breakdown. |
|
|
158
|
-
| `override` | Logged safety bypass with reason. |
|
|
159
|
-
| `security` | Security leak scanner — regex-based credential/token detection. |
|
|
160
|
-
| `gc` | Kuma garbage collection — orphan cleanup, VACUUM, index maintenance. |
|
|
161
|
-
| `doctor` | Kuma health diagnostics — DB integrity, schema health, process status, verification history. |
|
|
162
|
-
| `portability` | Check path portability — no absolute paths in stored data. |
|
|
163
|
-
| `gitignore` | Auto-configure `.gitignore` to include `.kuma/`. |
|
|
164
|
-
| `clean` | Purge scratch directory + reset drift warnings. |
|
|
165
|
-
| `policy` | Policy-as-Code engine — evaluate commands against `.kuma/policy.yml` (Issue #24). |
|
|
166
|
-
| `ast` / `validate` | AST-based code validation — validate JS/TS code structure & patterns (Issue #22). |
|
|
239
|
+
> Hooks are registered in `.claude/settings.json` (PreToolUse) — not stored under `.kuma/`.
|
|
167
240
|
|
|
168
|
-
|
|
241
|
+
> Research cache is **not** a folder — it lives in the `research_cache` table inside `kuma.db`.
|
|
169
242
|
|
|
170
|
-
|
|
243
|
+
**Key principle:** Context is per-project, per-agent. No shared state between projects.
|
|
171
244
|
|
|
172
|
-
|
|
245
|
+
---
|
|
173
246
|
|
|
174
|
-
|
|
175
|
-
|------|---------|--------|-----|
|
|
176
|
-
| 🔥 **Exponential** | `arch_flow` + `gotcha` | **High signal architecture & bug shield** | Complete architecture flows (max 5 core files) save massive file-reading next session. Gotchas prevent bug re-discovery. |
|
|
177
|
-
| 🟡 **Linear** | `decision` + `research_save` | **Useful but not multiplicative** | Decisions preserve rationale context. Research saves create searchable cache. |
|
|
178
|
-
| 🟢 **SKIP** | Function/class/component nodes | **Not worth MCP call — grep is faster** | Use `grep funcName(`, `grep class ClassName`, `glob **/*Component*` instead |
|
|
247
|
+
## Why Kuma?
|
|
179
248
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
249
|
+
| Problem | Without Kuma | With Kuma |
|
|
250
|
+
|---------|--------------|-----------|
|
|
251
|
+
| **Context** | Agent forgets project-specific patterns | Knowledge graph persists across sessions |
|
|
252
|
+
| **Safety** | Agent may break critical code | Policy engine blocks risky operations |
|
|
253
|
+
| **Impact** | Agent doesn't know what's affected | Impact analysis traces dependencies |
|
|
254
|
+
| **Coordination** | Multiple agents conflict | Per-agent session state + audit trail avoid collisions |
|
|
255
|
+
| **Memory** | Agent repeats past mistakes | Decision memory + gotchas prevent loops |
|
|
256
|
+
| **Reversibility** | Hard to undo changes | Checkpoint snapshots + selective undo |
|
|
257
|
+
| **Staleness** | Knowledge becomes outdated | Drift detection + gotcha staleness checks flag stale data |
|
|
185
258
|
|
|
186
259
|
---
|
|
187
260
|
|
|
188
|
-
##
|
|
261
|
+
## Installation
|
|
262
|
+
|
|
263
|
+
```bash
|
|
264
|
+
# Global install
|
|
265
|
+
npm install -g @plumpslabs/kuma
|
|
189
266
|
|
|
190
|
-
|
|
267
|
+
# Or use npx (no install needed)
|
|
268
|
+
npx -y @plumpslabs/kuma
|
|
191
269
|
|
|
192
|
-
|
|
270
|
+
# With pnpm
|
|
271
|
+
pnpm add -g @plumpslabs/kuma
|
|
272
|
+
```
|
|
193
273
|
|
|
194
|
-
|
|
195
|
-
- Syncs **anonymized** patterns (error types, tool names, language — no source code, no file names, no git history)
|
|
196
|
-
- Helps Kuma learn patterns across projects ("this error pattern is common in Go projects")
|
|
197
|
-
- Data goes to **your own VPS**, not a public server
|
|
274
|
+
### Requirements
|
|
198
275
|
|
|
199
|
-
|
|
276
|
+
- Node.js >= 18.0.0
|
|
277
|
+
- No native dependencies (uses WASM for SQLite)
|
|
200
278
|
|
|
201
279
|
---
|
|
202
280
|
|
|
203
|
-
##
|
|
281
|
+
## CLI Commands
|
|
204
282
|
|
|
205
|
-
|
|
283
|
+
```bash
|
|
284
|
+
# Start MCP server (default)
|
|
285
|
+
kuma
|
|
206
286
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
├── kuma.db ← Knowledge graph, research cache, audit trail, change log
|
|
213
|
-
├── init.md ← Behavioral rules for the AI agent
|
|
214
|
-
├── config.json ← Per-project settings
|
|
215
|
-
├── policy.yml ← Safety policy
|
|
216
|
-
├── research/ ← Research records (one JSON per scope)
|
|
217
|
-
└── memories/ ← Persistent decisions, conventions, glossary
|
|
218
|
-
```
|
|
287
|
+
# Start Kuma Studio dashboard
|
|
288
|
+
kuma studio
|
|
289
|
+
|
|
290
|
+
# Initialize a project
|
|
291
|
+
kuma init
|
|
219
292
|
|
|
220
|
-
|
|
293
|
+
# Show version
|
|
294
|
+
kuma --version
|
|
221
295
|
|
|
222
|
-
|
|
296
|
+
# Show help
|
|
297
|
+
kuma --help
|
|
298
|
+
```
|
|
223
299
|
|
|
224
300
|
---
|
|
225
301
|
|
|
226
|
-
##
|
|
302
|
+
## Configuration
|
|
227
303
|
|
|
228
|
-
|
|
304
|
+
### MCP Client Configuration
|
|
229
305
|
|
|
306
|
+
Add to your MCP client config (e.g., Claude Desktop):
|
|
307
|
+
|
|
308
|
+
```json
|
|
309
|
+
{
|
|
310
|
+
"mcpServers": {
|
|
311
|
+
"kuma": {
|
|
312
|
+
"command": "npx",
|
|
313
|
+
"args": ["-y", "@plumpslabs/kuma"]
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
}
|
|
230
317
|
```
|
|
231
|
-
# 1. Understand the project
|
|
232
|
-
kuma_context({ action: "init", goal: "add password reset" })
|
|
233
318
|
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
319
|
+
### Environment Variables
|
|
320
|
+
|
|
321
|
+
| Variable | Description | Default |
|
|
322
|
+
|----------|-------------|---------|
|
|
323
|
+
| `KUMA_DB_PATH` | Custom database path | `.kuma/kuma.db` |
|
|
324
|
+
| `KUMA_POLICY_PATH` | Custom policy file | `.kuma/policy.yml` |
|
|
325
|
+
| `KUMA_STUDIO_PORT` | Studio server port | `3322` |
|
|
326
|
+
|
|
327
|
+
---
|
|
328
|
+
|
|
329
|
+
## Development
|
|
237
330
|
|
|
238
|
-
|
|
331
|
+
```bash
|
|
332
|
+
# Clone the repo
|
|
333
|
+
git clone https://github.com/plumpslabs/kuma.git
|
|
334
|
+
cd kuma
|
|
239
335
|
|
|
240
|
-
#
|
|
241
|
-
|
|
336
|
+
# Install dependencies
|
|
337
|
+
pnpm install
|
|
242
338
|
|
|
243
|
-
#
|
|
244
|
-
|
|
245
|
-
action: "decision",
|
|
246
|
-
decisionAction: "record",
|
|
247
|
-
title: "Use JWT for password reset tokens",
|
|
248
|
-
context: "Need stateless tokens that expire in 15min",
|
|
249
|
-
rationale: "No session store needed, mobile-compatible",
|
|
250
|
-
outcome: "Implemented JwtPasswordResetService"
|
|
251
|
-
})
|
|
339
|
+
# Build
|
|
340
|
+
pnpm run build:all
|
|
252
341
|
|
|
253
|
-
#
|
|
254
|
-
|
|
342
|
+
# Run tests
|
|
343
|
+
pnpm test
|
|
255
344
|
|
|
256
|
-
#
|
|
257
|
-
|
|
345
|
+
# Start studio in dev mode
|
|
346
|
+
pnpm run studio:dev
|
|
258
347
|
```
|
|
259
348
|
|
|
260
349
|
---
|
|
261
350
|
|
|
262
|
-
##
|
|
351
|
+
## Power Curve: What to Record
|
|
263
352
|
|
|
264
|
-
|
|
|
265
|
-
|
|
266
|
-
|
|
|
267
|
-
|
|
|
268
|
-
|
|
|
269
|
-
|
|
|
270
|
-
|
|
|
271
|
-
|
|
|
272
|
-
|
|
|
353
|
+
| What to Record | When | Why | Impact |
|
|
354
|
+
|----------------|------|-----|--------|
|
|
355
|
+
| `arch_flow` | After tracing a complete flow | Saves 5-10 files next session | 🔴 Exponential |
|
|
356
|
+
| `gotcha` | IMMEDIATELY when finding bugs | Prevents re-discovery | 🔴 Exponential |
|
|
357
|
+
| `decision` | When choosing between options | Preserves rationale | 🔴 Exponential |
|
|
358
|
+
| `feature` | When identifying a module | Creates owns edges to files | 🔴 Exponential |
|
|
359
|
+
| `research_save` | After exploring an area | Creates search cache | 🔴 Exponential |
|
|
360
|
+
| Function/class nodes | Skip | Agent can grep/glob | 🟢 Skip |
|
|
361
|
+
| Import edges | Skip | Agent can read imports | 🟢 Skip |
|
|
362
|
+
| Visual graph | Skip | For humans, not AI | 🟢 Skip |
|
|
273
363
|
|
|
274
364
|
---
|
|
275
365
|
|
|
276
366
|
## License
|
|
277
367
|
|
|
278
|
-
MIT
|
|
368
|
+
MIT — use freely in personal and commercial projects.
|
|
279
369
|
|
|
280
|
-
|
|
370
|
+
---
|
|
281
371
|
|
|
282
|
-
|
|
372
|
+
## Community
|
|
283
373
|
|
|
284
|
-
[
|
|
374
|
+
- **GitHub:** [github.com/plumpslabs/kuma](https://github.com/plumpslabs/kuma)
|
|
375
|
+
- **Issues:** [github.com/plumpslabs/kuma/issues](https://github.com/plumpslabs/kuma/issues)
|
|
376
|
+
- **npm:** [npm.im/@plumpslabs/kuma](https://npm.im/@plumpslabs/kuma)
|
|
285
377
|
|
|
286
|
-
|
|
378
|
+
---
|
|
379
|
+
|
|
380
|
+
<p align="center">
|
|
381
|
+
<sub>Built with 🧠 by the Kuma community</sub>
|
|
382
|
+
</p>
|