@plumpslabs/kuma 2.3.17 → 2.3.18

package/dist/{chunk-AJ7HHUDW.js → chunk-ZIXY2COZ.js}

@@ -76,14 +76,16 @@ var BOOTSTRAP_LINES = [
   '  2. `kuma_safety({ action: "guard" })`                     \u2014 Safety check before work',
   '  3. `kuma_context({ action: "research", scope: "<area>" })` \u2014 Research before editing',
   "  4. *(edit/read using native tools)*",
-  '  5. `kuma_memory({ action: "research_save", ... })`        \u2014 IMMEDIATELY after every read/grep (inline)',
-  '  6. `kuma_memory({ action: "gotcha" })`                    \u2014 IMMEDIATELY when bug/quirks found (inline)',
-  '  7. `kuma_memory({ action: "arch_flow" })`                 \u2014 IMMEDIATELY after tracing each flow hop (inline)',
-  '  8. `kuma_memory({ action: "decision" })`                  \u2014 IMMEDIATELY when choosing between options (inline)',
+  '  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 value)',
+  '  7. `kuma_memory({ action: "arch_flow" })`                 \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential value)',
+  '  8. `kuma_memory({ action: "decision" })`                  \u2014 When choosing between options (preserves rationale)',
   '  9. `kuma_safety({ action: "verify", ... })`               \u2014 Run tests / confirm nothing broken',
   ' 10. `kuma_context({ action: "changes" })`                  \u2014 Review session activity',
   "",
-  "\u{1F504} Record findings INLINE as you work \u2014 not just at steps 5-8. Every read/grep = mini research_save.",
+  "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 each record saves 5-10 files next session.",
+  "   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.",
   "",
   "\u26D4 Do NOT skip steps 5-10 after research \u2014 even if no code was changed.",
@@ -309,20 +311,43 @@ function generateInitMdContent() {
     "> \u26A0\uFE0F **Research-only sessions included.** Workflow ini wajib meskipun session hanya membaca/riset tanpa code changes.",
     "",
     "> \u{1F9E0} **Graph Philosophy:** Record findings INLINE as you work, not just at the end. Every time you read a",
-    "> file, grep a pattern, or trace a flow \u2014 call `research_save` immediately to persist file/func/import nodes.",
+    "> file, grep a pattern, or trace a flow \u2014 call `research_save` immediately to persist what you learned.",
     "> The knowledge graph accumulates across sessions. The more you use it, the richer it becomes.",
     "",
-    "**AUTO-RECORDED nodes/edges** (Kuma scanner detects these automatically):",
-    "- Files, Functions, Classes \u2192 created as graph nodes",
-    "- Imports, Calls, Extends \u2192 created as graph edges",
-    "- Variables, Components, Routes \u2192 created when detected",
-    "",
-    "**RECORD INLINE \u2014 Don't wait for steps 5-8:**",
-    "- After EVERY `read` that finds new files \u2192 call `research_save` mini (persist file nodes)",
-    "- After EVERY `grep` that discovers new functions \u2192 call `research_save` (persist function nodes)",
-    "- When you discover a bug/quirk \u2192 call `gotcha` IMMEDIATELY (not at step 6)",
-    "- When you trace a data flow hop \u2192 call `arch_flow` IMMEDIATELY (not at step 7)",
-    "- When you choose between options \u2192 call `decision` IMMEDIATELY (not at step 8)",
+    "> \u{1F52C} **Scanner vs Inline Recording:**",
+    "> \u2022 Scanner = cold start only. Auto-detects structure in TS/JS/TSX/JSX files during research step 3.",
+    "> \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.",
+    "",
+    "**AUTO-RECORDED (cold start scanner \u2014 TS/JS only):**",
+    "- Files, Functions, Classes \u2192 scanned during research step 3",
+    "- Imports, Calls, Extends \u2192 scanned edges",
+    "- Components, Routes \u2192 scanned when patterns match",
+    "",
+    "\u{1F534} **MUST RECORD \u2014 High Impact (use MCP):**",
+    "- `arch_flow` \u2014 IMMEDIATELY after each flow hop. Saves reading 5-10 files next session.",
+    "- `gotcha` \u2014 IMMEDIATELY when bug/quirk found. No re-research needed.",
+    "- `decision` \u2014 IMMEDIATELY when choosing. Preserves rationale context.",
+    "- `research_save` \u2014 After exploring area. Creates searchable cache + graph file node.",
+    "",
+    "\u{1F7E2} **SKIP \u2014 Low Impact (agent can grep faster):**",
+    "- Function/class nodes \u2192 grep `funcName(` / `class ClassName`",
+    "- Component nodes \u2192 glob `**/*ComponentName*`",
+    "- Import edges \u2192 check imports directly",
+    "- Route nodes \u2192 check router file directly",
+    "- Visual graph \u2192 for humans, not AI agents",
+    "",
+    "**RECORD INLINE \u2014 Focus on high-impact actions:**",
+    "- Finished tracing a flow? \u2192 `arch_flow` IMMEDIATELY (saves reading 5-10 files next session)",
+    "- Found a bug/quirk? \u2192 `gotcha` IMMEDIATELY (no re-research needed)",
+    "- Chose between options? \u2192 `decision` IMMEDIATELY (preserves rationale)",
+    "- Explored a new area? \u2192 `research_save` (creates searchable cache)",
+    "",
+    "**SKIP recording these \u2014 grep/glob is faster:**",
+    "- Function/class nodes \u2192 just `grep funcName(` or `grep class ClassName`",
+    "- Component/route nodes \u2192 glob directly",
+    "- Import edges \u2192 read import statements",
+    "- Visual graph \u2192 for humans, not AI",
     "",
     "### STEP 5: Save Research (RECORD INLINE \u2014 After Every Read/Grep)",
     "```",
@@ -398,6 +423,7 @@ function generateInitMdContent() {
     "| `todo` | Persistent todo CRUD | When managing tasks |",
     "| `context` | Inject context notes | Additional notes when needed |",
     "| `domain_rules` | Layer 1: business rules | Record business rules when discovered |",
+    "| `add_node` | Create structural nodes (low impact \u2014 grep is faster) | Rarely needed; only for visualize debugging |",
     "| `layers` | Show all 3 layers summary | Overview memory layers |",
     "",
     "### \u{1F6E1}\uFE0F kuma_safety \u2014 Safety & Policy",
@@ -457,14 +483,15 @@ function generateInitMdContent() {
     "  2. kuma_safety    \u2192 guard               \u2014 Safety check",
     "  3. kuma_context   \u2192 research            \u2014 Research target area",
     "  --- EDIT/READ (use native tools) ---",
-    "  5. kuma_memory    \u2192 research_save       \u2014 Save findings (inline after every read/grep)",
-    "  6. kuma_memory    \u2192 gotcha              \u2014 Record bugs/quirks (inline when found)",
-    "  7. kuma_memory    \u2192 arch_flow           \u2014 Record data flow (inline after each hop)",
-    "  8. kuma_memory    \u2192 decision            \u2014 Record key decisions (inline when choosing)",
+    "  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)",
+    "  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",
     "",
-    "\u{1F504} Record INLINE as you work \u2014 not just at steps 5-8. Every read/grep = mini research_save.",
+    "\u{1F525} `arch_flow` + `gotcha` are EXPONENTIAL \u2014 each record saves 5-10 files next session.",
+    "\u{1F7E2} SKIP recording function/class/component nodes \u2014 grep/glob is faster.",
     "\u{1F9E0} Graph is persistent \u2014 nodes/edges accumulate across sessions.",
     "",
     "ON DISCOVERY (When needed):",
@@ -472,14 +499,19 @@ function generateInitMdContent() {
     "  kuma_memory \u2192 context        \u2014 Additional notes",
     "  kuma_memory \u2192 todo           \u2014 Task management",
     "  kuma_memory \u2192 mine           \u2014 Historical context",
+    "  kuma_memory \u2192 add_node       \u2014 Manual function/class/component node (for visualize)",
     "```",
     "",
     "## \u{1F9E0} How the Scanner Works",
     "",
-    "Kuma's code scanner (`kumaCodeScanner.ts`) uses **regex-based pattern matching**",
-    "to detect code structure. It is NOT a full AST parser (no Babel/TypeScript compiler dependency).",
+    "Kuma's code scanner (`kumaCodeScanner.ts`) uses **lightweight regex-based pattern matching**",
+    "for **cold start** \u2014 giving new agents basic project structure on first session.",
+    "It is NOT a full AST parser (no Babel/TypeScript compiler dependency).",
+    "",
+    "**Scope:** TS/JS/TSX/JSX only. Non-TypeScript projects (Go, Ruby, Python, Rust, PHP, etc.)",
+    "rely entirely on **AI inline recording** \u2014 the agent records what it discovers as it works.",
     "",
-    "**What it detects (line-by-line regex):**",
+    "**What auto-scanner detects (line-by-line regex, TS/JS only):**",
     "- `function` declarations (named + async + generator)",
     "- Arrow function assignments (`const foo = (...) => ...`)",
     "- Typed arrow functions (`const foo: Type = (...) => ...`)",
@@ -491,41 +523,41 @@ function generateInitMdContent() {
     "- Test files (`.test.`, `.spec.`, `__tests__/`)",
     "",
     "**Known limitations:**",
-    "- Regex-based = can miss multi-line constructs or non-standard patterns",
+    "- Regex-based: can miss multi-line constructs or non-standard patterns",
     "- Complex generics or deeply nested syntax may not match",
     "- TypeScript advanced types may be partially parsed",
-    "- Scanner runs automatically during `kuma_context research` step 3",
+    "- Scanner runs during `kuma_context research` step 3 (max 200 files)",
     "- If scanner returns 0 structural nodes, the regex patterns didn't match your code style",
     "",
-    "**For richer code analysis:**",
-    "- Record findings INLINE as you read/grep \u2014 this builds the graph manually",
-    "- Call `research_save` after exploring files to persist function/class/import nodes",
-    "- The more you use Kuma, the richer the graph becomes (persistent across sessions)",
+    "**Key principle: Scanner = cold start, Inline Recording = primary.**",
+    "The scanner populates initial graph structure. Every subsequent session, the agent's",
+    "inline recording (research_save, gotcha, arch_flow, decision) enriches the graph further.",
+    "The more you use Kuma, the richer the graph becomes \u2014 persistent across sessions.",
     "",
     "---",
     "",
-    "## \u{1F4BE} How to Read Memory & Search the Graph",
+    "## \u{1F4BE} How to Retrieve Past Research \u2014 research_save \u2192 search",
     "",
-    "Kuma stores knowledge in two places:",
+    "Kuma stores knowledge in two places. The primary retrieval method for AI agents",
+    "is **`search`**, not `visualize`. Visualize is for human debugging, not agent consumption.",
     "",
-    "**1. Knowledge Graph (SQLite - `.kuma/kuma.db`)**",
-    "- Nodes: files, functions, classes, components, routes, tests, gotchas, decisions",
-    "- Edges: imports, calls, extends, contains, composes, routes",
-    '- Query: `kuma_memory({ action: "search", query: "<term>" })`',
-    "- Falls back to codebase grep if graph is empty",
+    "**Flow: research_save \u2192 search (for agents)**",
+    '- Save: `kuma_memory({ action: "research_save", scope: "<file or area>", confidence: 0.8 })`',
+    '- Retrieve: `kuma_memory({ action: "search", query: "<term>" })`',
+    '- Auto-load: `kuma_context({ action: "research", scope: "<area>" })`',
+    '- List cache: `kuma_context({ action: "researches" })`',
     "",
-    "**2. Research Cache (SQLite - `.kuma/kuma.db`)**",
-    '- Saved via `kuma_memory({ action: "research_save", scope: "<area>", confidence: 0.8 })`',
-    '- List: `kuma_context({ action: "researches" })`',
-    '- Auto-loaded during `kuma_context({ action: "research", scope: "<area>" })`',
+    "**Key design:** `research_save` now creates BOTH research cache entries AND",
+    "knowledge graph nodes (file + research scope). This means `search` finds",
+    "past research even if the graph scanner didn't detect your code style.",
     "",
-    "**Quick memory reading tips:**",
+    "**Quick retrieval tips:**",
+    '- `kuma_memory({ action: "search", query: "<term>" })` \u2014 **primary method**. Finds past research + graph nodes + codebase',
+    '- `kuma_context({ action: "research", scope: "<area>" })` \u2014 deep 5-step research, auto-loads past cache',
     '- `kuma_context({ action: "init" })` \u2014 shows graph stats + recent research + health score',
-    '- `kuma_context({ action: "research", scope: "<area>" })` \u2014 deep research with graph query',
-    '- `kuma_memory({ action: "search", query: "<term>" })` \u2014 search all memories + graph',
-    '- `kuma_context({ action: "visualize" })` \u2014 Mermaid diagram of the graph',
     '- `kuma_context({ action: "drift" })` \u2014 check if memories are stale vs actual code',
     '- `kuma_context({ action: "changes" })` \u2014 view session activity log',
+    '- `kuma_context({ action: "visualize" })` \u2014 (human debugging) Mermaid diagram of the graph',
     "",
     "---",
     "",
@@ -598,14 +630,15 @@ function handleOpencodeSecondary(root, results) {
       '  2. `kuma_kuma_safety({ action: "guard" })`                            \u2014 Safety check before work',
       '  3. `kuma_kuma_context({ action: "research", scope: "<area>" })`        \u2014 Research before editing',
       "  4. *(edit/read using native tools)*",
-      '  5. `kuma_kuma_memory({ action: "research_save", ... })`               \u2014 Save findings (inline after every read/grep)',
-      '  6. `kuma_kuma_memory({ action: "gotcha" })`                           \u2014 Record bugs/quirks (inline when found)',
-      '  7. `kuma_kuma_memory({ action: "arch_flow" })`                        \u2014 Record data flow (inline after each hop)',
-      '  8. `kuma_kuma_memory({ action: "decision" })`                         \u2014 Record key decisions (inline when choosing)',
+      '  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)',
+      '  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',
       "",
-      "\u{1F504} Record findings INLINE as you work \u2014 Every read/grep = mini research_save.",
+      "\u{1F525} `arch_flow` + `gotcha` = EXPONENTIAL value. Each record saves 5-10 files next session.",
+      "\u{1F7E2} SKIP recording function/class/component nodes \u2014 grep/glob is faster.",
       "\u{1F9E0} Graph is persistent \u2014 nodes/edges accumulate across sessions.",
       "",
       "\u26A0\uFE0F **OpenCode platform note:** Tool names are prefixed with `kuma_kuma_*`",
@@ -729,14 +762,15 @@ function getCombinedAgentsMd(selectedTypes) {
     '  2. `[kuma_]safety({ action: "guard" })`                     \u2014 Safety check before editing',
     '  3. `[kuma_]context({ action: "research", scope: "<area>" })` \u2014 Research before editing',
     "  4. *(edit/read using native tools)*",
-    '  5. `[kuma_]memory({ action: "research_save", ... })`        \u2014 Save all findings',
-    '  6. `[kuma_]memory({ action: "gotcha" })`                    \u2014 Record bugs/quirks found',
-    '  7. `[kuma_]memory({ action: "arch_flow" })`                 \u2014 Record data flow if mapped',
-    '  8. `[kuma_]memory({ action: "decision" })`                  \u2014 Record key findings/decisions',
+    '  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)',
+    '  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',
     "",
-    "\u{1F504} Record findings INLINE as you work \u2014 Every read/grep = mini research_save.",
+    "\u{1F525} `arch_flow` + `gotcha` = EXPONENTIAL value. Each record saves 5-10 files next session.",
+    "\u{1F7E2} SKIP recording function/class/component nodes \u2014 grep/glob is faster.",
     "\u{1F9E0} Graph is persistent \u2014 nodes/edges accumulate across sessions.",
     "",
     "\u26D4 Do NOT skip steps 5-10 after research \u2014 even if no code was changed.",
@@ -946,15 +980,16 @@ function handleQuickrefGeneration(root, results) {
     '  2. `kuma_safety({ action: "guard" })`                             \u2014 Safety check',
     '  3. `kuma_context({ action: "research", scope: "<area>" })`         \u2014 Research',
     "  4. *(edit/read using native tools)*",
-    '  5. `kuma_memory({ action: "research_save", ... })`                \u2014 Save findings (inline after every read)',
-    '  6. `kuma_memory({ action: "gotcha" })`                            \u2014 Gotchas (inline when found)',
-    '  7. `kuma_memory({ action: "arch_flow" })`                         \u2014 Arch flow (inline after each hop)',
-    '  8. `kuma_memory({ action: "decision" })`                          \u2014 Decision (inline when choosing)',
-    '  9. `kuma_safety({ action: "verify", ... })`                       \u2014 Verify',
-    ' 10. `kuma_context({ action: "changes" })`                          \u2014 Review changes',
-    "",
-    "\u{1F504} Record INLINE as you work \u2014 Every read/grep = mini research_save.",
-    "\u{1F9E0} Graph is persistent \u2014 accumulates across sessions.",
+    '  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)',
+    '  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',
+    "",
+    "\u{1F525} `arch_flow` + `gotcha` = EXPONENTIAL value. Each record saves 5-10 files next session.",
+    "\u{1F7E2} SKIP recording function/class/component nodes \u2014 grep/glob is faster.",
+    "\u{1F9E0} Graph is persistent \u2014 nodes/edges accumulate across sessions.",
     "",
     "\u26D4 Steps 5-10 are mandatory even for research-only sessions!",
     "",

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   ALL_CONFIG_TYPES,
   formatInitResults,
   runInit
-} from "./chunk-AJ7HHUDW.js";
+} from "./chunk-ZIXY2COZ.js";
 import {
   formatDecisionTemplate,
   getProactiveMemories,
@@ -336,7 +336,7 @@ async function handleResearch(params) {
     lines.push("  \u26A0\uFE0F Graph query failed");
   }
   try {
-    const { scanCodebase } = await import("./kumaCodeScanner-QYQUL4W6.js");
+    const { scanCodebase } = await import("./kumaCodeScanner-2RDHZ5F4.js");
     const scanResult = await scanCodebase({ scope, maxFiles: 100 });
     if (scanResult.nodeCount > 0 || scanResult.edgeCount > 0) {
       lines.push(`  \u{1F52C} Auto-scanned ${scanResult.filesScanned} files \u2192 ${scanResult.nodeCount} nodes, ${scanResult.edgeCount} edges`);
@@ -670,7 +670,13 @@ var MEMORY_ALIASES = {
   // Skills synonyms
   "skills": "skills",
   "distilled-skills": "skills",
-  "skill-list": "skills"
+  "skill-list": "skills",
+  // Add node synonyms
+  "add_node": "add_node",
+  "add-node": "add_node",
+  "node": "add_node",
+  "create-node": "add_node",
+  "record-node": "add_node"
 };
 async function handleMemory(params) {
   const rawAction = params.action || "session";
@@ -716,6 +722,8 @@ async function handleMemory(params) {
       return handleTrajectoryList(params);
     case "skills":
       return handleSkillsList(params);
+    case "add_node":
+      return handleAddNode(params);
     default:
       return `Unknown action "${action}".`;
   }
@@ -754,6 +762,17 @@ async function handleResearchSave(params) {
     validatedAt: (/* @__PURE__ */ new Date()).toISOString()
   });
   await saveResearchCache(scope, record, void 0, params.confidence);
+  try {
+    const { upsertNode, nodeId } = await import("./kumaGraph-GUQM75WL.js");
+    await upsertNode({ id: nodeId("file", scope), type: "file", name: scope });
+    await upsertNode({
+      id: `research::${scope}`,
+      type: "variable",
+      name: `research:${scope}`,
+      metadata: { confidence: params.confidence || 0.8 }
+    });
+  } catch {
+  }
   try {
     const researchDir = path2.join(getProjectRoot(), ".kuma", "research");
     if (!fs2.existsSync(researchDir)) fs2.mkdirSync(researchDir, { recursive: true });
@@ -955,6 +974,39 @@ async function handleSkillsList(_params) {
   const { listDistilledSkills } = await import("./kumaTrajectory-T6DXGOG4.js");
   return await listDistilledSkills();
 }
+async function handleAddNode(params) {
+  const type = params.title;
+  const name = params.content;
+  const filePath = params.scope;
+  if (!type || !name) {
+    return "\u26A0\uFE0F `title` (node type: function/class/component/file/api_route/test) and `content` (node name) required.\nExample: kuma_memory({ action: 'add_node', title: 'function', content: 'sendMessage', scope: 'ChatService.ts' })";
+  }
+  const validTypes = ["function", "class", "component", "file", "api_route", "test"];
+  if (!validTypes.includes(type)) {
+    return `\u26A0\uFE0F Invalid type "${type}". Valid types: ${validTypes.join(", ")}`;
+  }
+  try {
+    const { upsertNode, nodeId, addEdge } = await import("./kumaGraph-GUQM75WL.js");
+    const nodeIdStr = filePath ? `${type}::${filePath}::${name}` : nodeId(type, name);
+    await upsertNode({
+      id: nodeIdStr,
+      type,
+      name,
+      filePath
+    });
+    if (filePath) {
+      const fileNodeId = nodeId("file", filePath);
+      await upsertNode({ id: fileNodeId, type: "file", name: filePath });
+      try {
+        await addEdge({ sourceId: fileNodeId, targetId: nodeIdStr, type: "contains" });
+      } catch {
+      }
+    }
+    return `\u2705 Node created: **${name}** (${type})${filePath ? ` \u2014 ${filePath}` : ""}`;
+  } catch (err) {
+    return `\u274C Failed to create node: ${err}`;
+  }
+}
 async function handleLayersSummary(_params) {
   const { getLayersSummary } = await import("./domainRules-ED6EOFVY.js");
   return getLayersSummary();
@@ -2190,9 +2242,9 @@ function registerAllTools(server) {
   );
   server.tool(
     "kuma_memory",
-    "**Call AFTER research/editing every session** (including research-only). Record INLINE as you work.\n\nRECORD INLINE (call IMMEDIATELY during research):\n\u2022 STEP 5: `research_save` \u2014 every read/grep that finds new files/functions. Don't wait!\n\u2022 STEP 6: `gotcha` \u2014 IMMEDIATELY when you discover bugs/quirks. Record INLINE, not at the end.\n\u2022 STEP 7: `arch_flow` \u2014 IMMEDIATELY after EACH flow hop trace. Record before next task.\n\u2022 STEP 8: `decision` \u2014 IMMEDIATELY when choosing between options or finding architecture patterns.\n\nON DISCOVERY (when you encounter something):\n\u2022 `domain_rules` \u2014 uncovered business rules? Save them!\n\u2022 `context` \u2014 need to inject extra notes? Use this!\n\u2022 `todo` \u2014 create persistent task items\n\u2022 `mine` \u2014 extract historical context from git log\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 every read/grep that finds new files. Creates searchable 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.",
     {
-      action: z.enum(["decision", "mine", "research_save", "session", "heal", "search", "changes", "todo", "context", "benchmark", "decision_log", "domain_rules", "arch_flow", "gotcha", "layers", "federated", "gen_test", "trajectory", "skills"]).describe("Memory action: decision=ADR, mine=mine git log & comments, research_save=save, session=summary, heal=repair, search=search, changes=log, todo=manage todos, context=inject notes, benchmark=capture/diff, decision_log=manage decisions, domain_rules=Layer 1 business rules (Issue #17), arch_flow=Layer 2 architecture flow (Issue #17), gotcha=Layer 3 known gotchas (Issue #17/#21), layers=all 3 layers summary, federated=resolve federated kuma:// URI (Issue #27), gen_test=generate test from trajectory (Issue #28), trajectory=list trajectories, skills=list distilled skills"),
+      action: z.enum(["decision", "mine", "research_save", "session", "heal", "search", "changes", "todo", "context", "benchmark", "decision_log", "domain_rules", "arch_flow", "gotcha", "layers", "federated", "gen_test", "trajectory", "skills", "add_node"]).describe("Memory action: decision=ADR, mine=mine git log & comments, research_save=save (creates file + graph node), session=summary, heal=repair, search=search, changes=log, todo=manage todos, context=inject notes, benchmark=capture/diff, decision_log=manage decisions, domain_rules=Layer 1 business rules (Issue #17), arch_flow=Layer 2 architecture flow (Issue #17), gotcha=Layer 3 known gotchas (Issue #17/#21), layers=all 3 layers summary, federated=resolve federated kuma:// URI (Issue #27), gen_test=generate test from trajectory (Issue #28), trajectory=list trajectories, skills=list distilled skills, add_node=manually create function/class/component structural nodes"),
       scope: z.string().optional().describe("Scope for research_save/search/todo/context/mine/federated"),
       query: z.string().optional().describe("Search query for search action"),
       content: z.string().optional().describe("Content/notes for research_save / context"),
@@ -2571,7 +2623,7 @@ async function main() {
   });
   (async () => {
     try {
-      const { generateInitMdContent } = await import("./init-BC7FG4C2.js");
+      const { generateInitMdContent } = await import("./init-RUKOPMX6.js");
       const fs7 = await import("fs");
       const path7 = await import("path");
       const initMdPath = path7.resolve(process.cwd(), ".kuma/init.md");
@@ -2588,7 +2640,7 @@ async function main() {
   (async () => {
     try {
       const { detectAgent, getSkillPath, getAgentLabel } = await import("./agentDetector-YOWQVJFR.js");
-      const { generateSkill, getSecondaryFiles } = await import("./skillGenerator-GYEDLFZP.js");
+      const { generateSkill, getSecondaryFiles } = await import("./skillGenerator-PWEJKZNX.js");
       const fs7 = await import("fs");
       const path7 = await import("path");
       const detection = detectAgent();

package/dist/{init-BC7FG4C2.js → init-RUKOPMX6.js}

@@ -4,7 +4,7 @@ import {
   formatInitResults,
   generateInitMdContent,
   runInit
-} from "./chunk-AJ7HHUDW.js";
+} from "./chunk-ZIXY2COZ.js";
 import "./chunk-E2KFPEBT.js";
 export {
   ALL_CONFIG_TYPES,

package/dist/{kumaCodeScanner-QYQUL4W6.js → kumaCodeScanner-2RDHZ5F4.js}

@@ -27,11 +27,12 @@ var CLASS_RE = /(?:export\s+)?(?:abstract\s+)?class\s+(\w+)(?:\s+extends\s+(\w+)
 var IMPORT_RE = /import\s+(?:\{([^}]*)\}\s+from\s+)?(?:\w+\s+from\s+)?(?:\*\s+as\s+\w+\s+from\s+)?['"]([^'"]+)['"]/g;
 var JSX_RETURN_RE = /return\s*\(?\s*</;
 var JSX_ELEMENT_RE = /<([A-Z]\w+)[\s/>]/g;
+var JSX_IMPLICIT_RE = /=>\s*(?:\(\s*)?</;
 var EXPRESS_ROUTE_RE = /\.(get|post|put|delete|patch)\s*\(\s*['"]([^'"]+)['"]\s*,\s*(\w+)/g;
 var HONO_ROUTE_RE = /c\.(get|post|put|delete|patch)\s*\(\s*['"]([^'"]+)['"]/g;
-var TEST_PATTERNS = [".test.", ".spec.", "__tests__", "/test/"];
 var EXPORT_RE = /export\s+(?:default\s+)?(\w+)/g;
 var CALL_RE = /(\w+)\s*\(/g;
+var TEST_PATTERNS = [".test.", ".spec.", "__tests__", "/test/"];
 var knownComponents = /* @__PURE__ */ new Set();
 var knownFunctions = /* @__PURE__ */ new Set();
 var symbolLocations = /* @__PURE__ */ new Map();
@@ -236,11 +237,9 @@ function parseFile(filePath, content) {
       }
     }
   }
-  const JSX_IMPLICIT_RE = /=>\s*(?:\(\s*)?</;
   if (hasJSX) {
     for (const fn of [...result.functions]) {
       const fnStartLine = fn.line - 1;
-      const fnLine = lines[fnStartLine];
       const endLine = Math.min(fnStartLine + 50, lines.length);
       let isComponent = false;
       for (let i = fnStartLine; i < endLine; i++) {
@@ -249,12 +248,10 @@ function parseFile(filePath, content) {
           break;
         }
       }
-      if (!isComponent && JSX_IMPLICIT_RE.test(fnLine)) isComponent = true;
-      if (!isComponent && fnLine.includes("=>") && fnStartLine + 1 < endLine) {
+      if (!isComponent && JSX_IMPLICIT_RE.test(lines[fnStartLine])) isComponent = true;
+      if (!isComponent && fnStartLine + 1 < endLine) {
         const nextLine = lines[fnStartLine + 1].trim();
-        if (nextLine.startsWith("<") || nextLine.startsWith("(") || nextLine.startsWith("<>")) {
-          isComponent = true;
-        }
+        if (nextLine.startsWith("<") || nextLine.startsWith("(") || nextLine.startsWith("<>")) isComponent = true;
       }
       if (isComponent) {
         result.components.push({ name: fn.name, line: fn.line });

package/dist/{skillGenerator-GYEDLFZP.js → skillGenerator-PWEJKZNX.js}

@@ -10,14 +10,16 @@ var BOOTSTRAP = [
   '  2. `kuma_safety({ action: "guard" })`                     \u2014 Safety check before work',
   '  3. `kuma_context({ action: "research", scope: "<area>" })` \u2014 Research before editing',
   "  4. *(edit/read using native tools)*",
-  '  5. `kuma_memory({ action: "research_save", ... })`        \u2014 Save findings (inline after every read/grep)',
-  '  6. `kuma_memory({ action: "gotcha" })`                    \u2014 Record bugs/quirks (inline when found)',
-  '  7. `kuma_memory({ action: "arch_flow" })`                 \u2014 Record data flow (inline after each hop)',
-  '  8. `kuma_memory({ action: "decision" })`                  \u2014 Record key decisions (inline when choosing)',
+  '  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 value)',
+  '  7. `kuma_memory({ action: "arch_flow" })`                 \u2014 \u{1F525} IMMEDIATELY after each flow hop (exponential value)',
+  '  8. `kuma_memory({ action: "decision" })`                  \u2014 When choosing between options (preserves rationale)',
   '  9. `kuma_safety({ action: "verify", ... })`               \u2014 Run tests / confirm nothing broken',
   ' 10. `kuma_context({ action: "changes" })`                  \u2014 Review session activity',
   "",
-  "\u{1F504} Record findings INLINE as you work \u2014 Every read/grep = mini research_save.",
+  "\u{1F525} **Power Curve:** `arch_flow` + `gotcha` are EXPONENTIAL \u2014 each record saves 5-10 files next session.",
+  "   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.",
   "",
   "\u26D4 Do NOT skip steps 5-10 after research \u2014 even if no code was changed.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumpslabs/kuma",
-  "version": "2.3.17",
+  "version": "2.3.18",
   "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",