@plumpslabs/kuma 2.3.26 → 2.3.28

package/README.md

@@ -173,12 +173,12 @@ Not all recordings are equal. Kuma categorizes actions by their long-term impact
 
 | Tier | Actions | Impact | Why |
 |------|---------|--------|-----|
-| 🔥 **Exponential** | `arch_flow` + `gotcha` | **Each record saves 5-10 files next session** | Architecture flows multiply: 10 flow hops = agent skips 50-100 files. Gotchas prevent re-discovery of bugs. |
+| 🔥 **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. |
 | 🟡 **Linear** | `decision` + `research_save` | **Useful but not multiplicative** | Decisions preserve rationale context. Research saves create searchable cache. |
 | 🟢 **SKIP** | Function/class/component nodes | **Not worth MCP call — grep is faster** | Use `grep funcName(`, `grep class ClassName`, `glob **/*Component*` instead |
 
 **Rule of thumb:**
-- **ALWAYS record** `arch_flow` + `gotcha` inline — they're the highest-value actions
+- **Record `arch_flow`** after tracing a complete flow (max 5 core files) & **`gotcha`** inline when bugs are found
 - **Record** `decision` + `research_save` when relevant
 - **NEVER record** function/class/component nodes via MCP — native grep is faster
 - Let the auto-scanner handle structural nodes during research step 3

package/dist/index.js

@@ -2438,6 +2438,22 @@ async function upsertNode(node) {
       db.run(`INSERT INTO nodes_fts (rowid, name, metadata) VALUES (last_insert_rowid(), ?, ?)`, [node.name, metadata]);
     } catch {
     }
+    if (node.filePath && node.type !== "file") {
+      const fileNodeId = nodeId("file", node.filePath);
+      try {
+        db.run(`
+          INSERT INTO nodes (id, type, name, file_path, metadata, updated_at)
+          VALUES (?, 'file', ?, ?, '{}', strftime('%s','now'))
+          ON CONFLICT(id) DO NOTHING
+        `, [fileNodeId, node.filePath, node.filePath]);
+        db.run(`
+          INSERT INTO edges (source_id, target_id, type, weight, metadata, created_at)
+          VALUES (?, ?, 'contains', 1.0, '{}', strftime('%s','now'))
+          ON CONFLICT DO NOTHING
+        `, [fileNodeId, id]);
+      } catch {
+      }
+    }
     saveDb(db);
     try {
       const countResult = db.exec("SELECT COUNT(*) FROM nodes");
@@ -6307,6 +6323,21 @@ async function addGotcha(entry) {
       [entry.filePath, entry.description, severity, entry.workaround || null]
     );
     const mdResult = appendToLayer("gotcha", formatted);
+    try {
+      const { upsertNode: upsertNode2, addEdge: addEdge2, nodeId: nodeId2 } = await Promise.resolve().then(() => (init_kumaGraph(), kumaGraph_exports));
+      const fileNodeId = nodeId2("file", entry.filePath);
+      const gotchaNodeId = `gotcha::${entry.filePath}::${entry.description.substring(0, 30)}`;
+      await upsertNode2({ id: fileNodeId, type: "file", name: entry.filePath });
+      await upsertNode2({
+        id: gotchaNodeId,
+        type: "gotcha",
+        name: `gotcha:${entry.description.substring(0, 40)}`,
+        filePath: entry.filePath,
+        metadata: { severity, workaround: entry.workaround }
+      });
+      await addEdge2({ sourceId: fileNodeId, targetId: gotchaNodeId, type: "depends_on" });
+    } catch {
+    }
     saveDb();
     sessionMemory.recordToolCall("kuma_gotcha_add", {
       filePath: entry.filePath,
@@ -7940,7 +7971,7 @@ function opencodeAgentsMdTemplate() {
     '  9. `kuma_kuma_safety({ action: "verify", ... })`              \u2014 Run tests / confirm nothing broken',
     ' 10. `kuma_kuma_context({ action: "changes" })`                 \u2014 Review session activity',
     "",
-    "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 each record saves 5-10 files next session.",
+    "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 arch_flow records complete flow (max 5 core files), gotcha records bugs inline.",
     "   The more you record, the more overpowered the agent becomes. These are the highest-value actions.",
     "\u{1F7E2} **SKIP** recording function/class/component nodes \u2014 grep/glob is faster.",
     "\u{1F9E0} Knowledge graph is persistent \u2014 nodes/edges accumulate across sessions, getting richer over time.",
@@ -8051,12 +8082,12 @@ function antigravitySkillTemplate() {
     "  4. *(edit/read using native tools)*",
     '  5. `kuma_kuma_memory({ action: "research_save", ... })`       \u2014 After exploring area (creates search cache)',
     '  6. `kuma_kuma_memory({ action: "gotcha" })`                   \u2014 \u{1F525} IMMEDIATELY when bug found (exponential value)',
-    '  7. `kuma_kuma_memory({ action: "arch_flow" })`                \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential value)',
+    '  7. `kuma_kuma_memory({ action: "arch_flow" })`                \u2014 After tracing COMPLETE flow, max 5 core files',
     '  8. `kuma_kuma_memory({ action: "decision" })`                 \u2014 When choosing between options (preserves rationale)',
     '  9. `kuma_kuma_safety({ action: "verify", ... })`              \u2014 Run tests / confirm nothing broken',
     ' 10. `kuma_kuma_context({ action: "changes" })`                 \u2014 Review session activity',
     "",
-    "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 each record saves 5-10 files next session.",
+    "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 arch_flow records complete flow (max 5 core files), gotcha records bugs inline.",
     "   The more you record, the more overpowered the agent becomes. These are the highest-value actions.",
     "\u{1F7E2} **SKIP** recording function/class/component nodes \u2014 grep/glob is faster.",
     "\u{1F9E0} Knowledge graph is persistent \u2014 nodes/edges accumulate across sessions, getting richer over time.",
@@ -8146,6 +8177,11 @@ function generateInitMdContent() {
     "> \u2022 Inline Recording = primary method. You (the agent) record findings as you read/grep/edit.",
     "> \u2022 Non-TS/JS projects (Go, Ruby, Python, Rust, PHP) rely ENTIRELY on inline recording.",
     "",
+    "> \u{1F6E1}\uFE0F **Node Idempotency & Relational Integrity (Anti-Duplication & No Orphans):**",
+    "> \u2022 **Zero Duplicate Risk:** `research_save` and `add_node` are fully idempotent. Re-saving an existing scope/file updates metadata and timestamp without duplicating nodes.",
+    "> \u2022 **Zero Orphan Guarantee:** Every node created with a `filePath` or `scope` is automatically linked via a `contains` or `depends_on` edge to its parent file node.",
+    "> \u2022 **Always Connected:** Avoid recording standalone orphan entities; link findings to a core business domain or file path.",
+    "",
     "**AUTO-RECORDED (cold start scanner \u2014 TS/JS only):**",
     "- Files, Functions, Classes \u2192 scanned during research step 3",
     "- Imports, Calls, Extends \u2192 scanned edges",
@@ -8395,7 +8431,7 @@ function generateInitMdContent() {
     "  --- EDIT/READ (use native tools) ---",
     "  5. kuma_memory    \u2192 research_save       \u2014 After exploring area (creates search cache)",
     "  6. kuma_memory    \u2192 gotcha              \u2014 \u{1F525} IMMEDIATELY when bug found (exponential)",
-    "  7. kuma_memory    \u2192 arch_flow           \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential)",
+    "  7. kuma_memory    \u2192 arch_flow           \u2014 After tracing COMPLETE flow (max 5 core files)",
     "  8. kuma_memory    \u2192 decision            \u2014 When choosing (preserves rationale)",
     "  9. kuma_safety    \u2192 verify              \u2014 Run tests / confirm nothing broken",
     " 10. kuma_context   \u2192 changes             \u2014 Review session activity",
@@ -8532,7 +8568,7 @@ function handleOpencodeSecondary(root, results) {
       "  4. *(edit/read using native tools)*",
       '  5. `kuma_kuma_memory({ action: "research_save", ... })`               \u2014 After exploring area (creates search cache)',
       '  6. `kuma_kuma_memory({ action: "gotcha" })`                           \u2014 \u{1F525} IMMEDIATELY when bug found (exponential)',
-      '  7. `kuma_kuma_memory({ action: "arch_flow" })`                        \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential)',
+      '  7. `kuma_kuma_memory({ action: "arch_flow" })`                        \u2014 After tracing COMPLETE flow, max 5 core files',
       '  8. `kuma_kuma_memory({ action: "decision" })`                         \u2014 When choosing (preserves rationale)',
       '  9. `kuma_kuma_safety({ action: "verify", ... })`                      \u2014 Run tests / confirm nothing broken',
       ' 10. `kuma_kuma_context({ action: "changes" })`                         \u2014 Review session activity',
@@ -8663,7 +8699,7 @@ function getCombinedAgentsMd(selectedTypes) {
     "  4. *(edit/read using native tools)*",
     '  5. `[kuma_]memory({ action: "research_save", ... })`        \u2014 After exploring area (creates search cache)',
     '  6. `[kuma_]memory({ action: "gotcha" })`                    \u2014 \u{1F525} IMMEDIATELY when bug found (exponential)',
-    '  7. `[kuma_]memory({ action: "arch_flow" })`                 \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential)',
+    '  7. `[kuma_]memory({ action: "arch_flow" })`                 \u2014 After tracing COMPLETE flow (max 5 core files)',
     '  8. `[kuma_]memory({ action: "decision" })`                  \u2014 When choosing (preserves rationale)',
     '  9. `[kuma_]safety({ action: "verify", ... })`               \u2014 Run tests / confirm nothing broken',
     ' 10. `[kuma_]context({ action: "changes" })`                  \u2014 Review session activity',
@@ -9308,7 +9344,7 @@ var init_init = __esm({
       '  9. `kuma_safety({ action: "verify", ... })`               \u2014 Run tests / confirm nothing broken',
       ' 10. `kuma_context({ action: "changes" })`                  \u2014 Review session activity',
       "",
-      "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 each record saves 5-10 files next session.",
+      "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 arch_flow records complete flow (max 5 core files), gotcha records bugs inline.",
       "   The more you record, the more overpowered the agent becomes. These are the highest-value actions.",
       "\u{1F7E2} **SKIP** recording function/class/component nodes \u2014 grep/glob is faster.",
       "\u{1F9E0} Knowledge graph is persistent \u2014 nodes/edges accumulate across sessions, getting richer over time.",
@@ -10595,6 +10631,11 @@ async function handleResearchSave(params) {
         metadata = json_patch(COALESCE(nodes.metadata, '{}'), excluded.metadata),
         updated_at = excluded.updated_at
     `, [researchId, `research:${scope}`, JSON.stringify({ confidence: params.confidence || 0.8, last_findings: params.content || "" }), now]);
+    db.run(`
+      INSERT INTO edges (source_id, target_id, type, weight, metadata, created_at)
+      VALUES (?, ?, 'contains', 1.0, '{}', ?)
+      ON CONFLICT DO NOTHING
+    `, [fileId, researchId, now]);
     flushDb2(db);
   } catch {
   }
@@ -12424,7 +12465,7 @@ function registerAllTools(server) {
   );
   server.tool(
     "kuma_memory",
-    "**Call after research/editing** (including research-only). Record what matters, skip what doesn't.\n\n\u{1F534} MUST RECORD \u2014 High Impact (saves agent time next session):\n\u2022 STEP 5: `research_save` \u2014 after exploring area (creates search cache).\n\u2022 STEP 6: `gotcha` \u2014 IMMEDIATELY when you discover bugs/quirks. No re-research.\n\u2022 STEP 7: `arch_flow` \u2014 IMMEDIATELY after EACH flow hop. Saves reading 5-10 files.\n\u2022 STEP 8: `decision` \u2014 IMMEDIATELY when choosing between options. Preserves rationale.\n\n\u{1F7E2} SKIP using MCP (agent native tools are faster):\n\u2022 Function/class nodes \u2192 grep\n\u2022 Component/route nodes \u2192 glob or check directly\n\u2022 Import edges \u2192 read imports directly\n\u2022 Visual graph \u2192 for humans, not AI agents\n\nOther actions: session, heal, search, changes, benchmark, layers.",
+    "**Call after research/editing** (including research-only). Record what matters, skip what doesn't.\n\n\u{1F534} MUST RECORD \u2014 High Impact (saves agent time next session):\n\u2022 STEP 5: `research_save` \u2014 after exploring area (creates search cache).\n\u2022 STEP 6: `gotcha` \u2014 IMMEDIATELY when you discover bugs/quirks. No re-research.\n\u2022 STEP 7: `arch_flow` \u2014 AFTER tracing COMPLETE flow (max 5 core files).\n\u2022 STEP 8: `decision` \u2014 IMMEDIATELY when choosing between options. Preserves rationale.\n\n\u{1F7E2} SKIP using MCP (agent native tools are faster):\n\u2022 Function/class nodes \u2192 grep\n\u2022 Component/route nodes \u2192 glob or check directly\n\u2022 Import edges \u2192 read imports directly\n\u2022 Visual graph \u2192 for humans, not AI agents\n\nOther actions: session, heal, search, changes, benchmark, layers.",
     {
       action: z.enum(["decision", "mine", "research_save", "session", "heal", "search", "changes", "todo", "context", "benchmark", "decision_log", "domain_rules", "arch_flow", "gotcha", "layers", "add_node", "delete_node", "clear", "feature"]).describe("Memory action: decision=ADR, mine=mine git log & comments, research_save=save (creates file + graph node), session=summary, heal=repair, search=search (now with task retrieval + impact analysis), changes=log, todo=manage todos, context=inject notes, benchmark=capture/diff, decision_log=manage decisions, domain_rules=Layer 1 business rules, arch_flow=Layer 2 architecture flow (now auto-creates affects edges), gotcha=Layer 3 known gotchas, layers=all 3 layers summary, add_node=manually create function/class/component structural nodes, delete_node=delete a specific node/gotcha/todo/decision by ID or scope+target, clear=wipe all nodes/edges/gotchas, feature=record high-level feature with owns edges to files"),
       scope: z.string().optional().describe("Scope for research_save/search/todo/context/mine"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumpslabs/kuma",
-  "version": "2.3.26",
+  "version": "2.3.28",
   "description": "Safety-first context & orchestration engine for AI coding agents. MCP server with mandatory research pipeline, knowledge graph, impact analysis, decision memory, and safety guard — works with any MCP client.",
   "type": "module",
   "main": "dist/index.js",