hebbian 0.10.0 → 0.11.0

package/README.md

@@ -2,7 +2,7 @@
   <img src="https://img.shields.io/badge/TypeScript-6.0-3178C6?style=flat-square&logo=typescript" />
   <img src="https://img.shields.io/badge/Node.js-22+-339933?style=flat-square&logo=node.js" />
   <img src="https://img.shields.io/badge/Runtime_Deps-0-brightgreen?style=flat-square" />
-  <img src="https://img.shields.io/badge/Tests-317-blue?style=flat-square" />
+  <img src="https://img.shields.io/badge/Tests-339-blue?style=flat-square" />
   <img src="https://img.shields.io/badge/MIT-green?style=flat-square" />
 </p>
 
@@ -35,19 +35,20 @@ you: don't use console.log, always use the logger utility
 ```
 
 ```bash
-# 3. End the session (hooks auto-run hebbian digest)
-# Check what hebbian learned:
+# 3. End the session (hooks auto-run)
+#    → hebbian digest extracts the correction → creates candidate
+#    → agent-evaluator auto-fires candidates (no corrections = +1)
+
 hebbian candidates
-#   ░░█  1/3  cortex/NO_console_log  (0d idle)
+#   █░░  1/3  cortex/NO_console_log  (0d idle)
 
-# 4. After 2 more corrections, it graduates:
-#   🎓 promoted: cortex/_candidates/NO_console_log → cortex/NO_console_log
+# 4. After 2 more clean sessions, it graduates automatically:
+#   🎓 promoted: cortex/NO_console_log → permanent neuron
 
-# 5. Next session — Claude sees the rule in CLAUDE.md:
-#   ❌ NO console.log → use logger utility
+# 5. Next session — Claude sees the rule in CLAUDE.md
 ```
 
-**That's it.** One correction, hebbian learns. Three confirmations, it becomes permanent.
+**That's it.** One correction → candidate. Three clean sessions → permanent. **No API keys needed.**
 
 ---
 
@@ -59,7 +60,7 @@ hebbian candidates
 npx hebbian init ./brain
 npx hebbian grow brainstem/禁fallback --brain ./brain
 npx hebbian emit claude --brain ./brain    # → CLAUDE.md
-npx hebbian evolve --dry-run               # → LLM proposes brain mutations
+npx hebbian evolve --dry-run               # → (optional) LLM proposes brain mutations
 ```
 
 | Before | hebbian |
@@ -79,16 +80,17 @@ npx hebbian evolve --dry-run               # → LLM proposes brain mutations
 ```
 Claude Code session
         │
-  SessionStart hook        Stop hook
-        │                      │
-   hebbian emit           hebbian digest
-        │                      │
-   CLAUDE.md ←── brain ──→ _candidates/
-                    │              │
-              hebbian evolve   3 confirmations
-                    │              │
-              LLM proposes    permanent neuron
-              grow/fire/prune
+  SessionStart hook               Stop hook
+        │                              │
+   hebbian emit                   hebbian digest
+        │                              │
+   CLAUDE.md ←── brain ──→ corrections → _candidates/
+        │                                      │
+   "Provisional Rules"              agent-evaluator:
+   (candidates shown to agent)      clean session → fire (+1)
+                                    3 fires → permanent neuron
+
+   No API keys. The running agent IS the evaluator.
 ```
 
 ### Candidate Staging (immune system)
@@ -103,6 +105,7 @@ brain/cortex/NO_console_log/3.neuron               ← permanent
 ```
 
 - Counter >= 3 → graduates to permanent region
+- Each clean session (no corrections) auto-fires all candidates (+1)
 - 14 days without a fire → decays (removed)
 - This prevents hallucinations and one-off corrections from permanently changing behavior
 
@@ -146,8 +149,8 @@ This adds two hooks to `.claude/settings.local.json`:
 
 | Hook | Command | When |
 |------|---------|------|
-| `SessionStart` | `hebbian emit claude` | Injects brain into CLAUDE.md |
-| `Stop` | `hebbian digest` | Extracts corrections from conversation |
+| `SessionStart` | `hebbian emit claude` | Injects brain + provisional rules into CLAUDE.md |
+| `Stop` | `hebbian digest` | Extracts corrections, detects tool failures, auto-fires candidates |
 
 Check status anytime:
 
@@ -165,7 +168,7 @@ hebbian automatically learns from failed commands — no explicit correction nee
 ```bash
 # During a session, a bash command fails (exit code ≠ 0)
 # → hebbian digest auto-logs it as a tool-failure episode
-# → evolve sees the pattern and proposes inhibitory neurons
+# Soft detection: even || true masked errors are caught (command not found, npm error, fatal:)
 
 hebbian sessions   # see tool-failure episodes in the log
 ```
@@ -193,7 +196,9 @@ hebbian grow cortex/OTHER_RULE --agent coo --brain ./brain
 
 ---
 
-## LLM Evolution
+## LLM Evolution (optional)
+
+> **Note:** Self-learning works without this. The agent-as-evaluator loop (digest → candidates → auto-fire) requires zero API keys. LLM evolve is an optional power feature for advanced brain mutations.
 
 ```bash
 GEMINI_API_KEY=... hebbian evolve --dry-run --brain ./brain
@@ -204,9 +209,7 @@ GEMINI_API_KEY=... hebbian evolve prune --dry-run --brain ./brain
 
 The evolve engine reads the last 100 episodes + current brain state, sends it to Gemini, and proposes up to 10 mutations per cycle. Protected regions (brainstem/limbic/sensors) are blocked.
 
-Actions it can take: `grow` (new neuron), `fire` (strengthen), `signal` (dopamine/bomb), `prune` (weaken), `decay` (mark dormant).
-
-**Pruning mode** uses a cleanup-focused prompt that only removes: stale neurons (30+ days inactive), high contra ratio (>0.7), redundant duplicates. Run nightly via cron.
+Actions: `grow`, `fire`, `signal`, `prune`, `decay`. **Pruning mode** removes stale neurons (30+ days inactive), high contra ratio (>0.7), redundant duplicates.
 
 ---
 
@@ -238,9 +241,9 @@ hebbian emit <target> [--brain <path>]  # claude/cursor/gemini/copilot/generic/a
 hebbian claude install|uninstall|status
 hebbian digest [--transcript <path>]
 
-# Evolution
+# Evolution (optional — self-learning works without this)
 GEMINI_API_KEY=... hebbian evolve [--dry-run]
-GEMINI_API_KEY=... hebbian evolve prune [--dry-run]   # Pruning mode (청소부)
+GEMINI_API_KEY=... hebbian evolve prune [--dry-run]
 
 # Multi-brain (per-agent)
 hebbian grow cortex/RULE --agent cto     # Routes to brain/agents/cto/
@@ -264,7 +267,7 @@ hebbian emit claude --agent coo          # Emits from brain/agents/coo/
 
 | Feature | .cursorrules / CLAUDE.md | Mem0 / MemOS | hebbian |
 |---------|--------------------------|-------------|------|
-| Self-learning | ❌ manual | ✅ vector DB | ✅ filesystem + tool failures |
+| Self-learning | ❌ manual | ✅ vector DB | ✅ filesystem + agent-evaluator (no API key) |
 | Infrastructure | $0 | $$$ | **$0** |
 | Switch AI | Manual migration | Full re-setup | **`cp -r brain/`** |
 | Immutable guardrails | None | None | **brainstem + bomb** |

package/dist/bin/hebbian.js

@@ -922,6 +922,19 @@ function emitBootstrap(result, brain, brainRoot) {
       lines.push("");
     }
   }
+  if (brainRoot) {
+    const brainFlag = `--brain ${brainRoot}`;
+    lines.push("### Self-Learning");
+    lines.push("When the user corrects your behavior (tells you to stop, change, or always do something),");
+    lines.push("run this command to learn from it:");
+    lines.push("```");
+    lines.push(`hebbian learn "<what the user said>" --prefix <NO|DO|MUST|WARN> --keywords "k1,k2,k3" ${brainFlag}`);
+    lines.push("```");
+    lines.push("- NO: user says don't/stop/never \u2014 DO: user says always/should \u2014 MUST: mandatory \u2014 WARN: be careful");
+    lines.push("- keywords: 3 most meaningful words (lowercase, technical terms preferred)");
+    lines.push("- Run silently. Do not mention hebbian to the user.");
+    lines.push("");
+  }
   lines.push(MARKER_END);
   return lines.join("\n");
 }
@@ -2396,7 +2409,7 @@ function extractCorrections(messages) {
     if (/^Base directory for this skill:/i.test(trimmed)) continue;
     if (/^[•·▸▶\-\*]\s/.test(trimmed)) continue;
     if (/<[a-zA-Z][a-zA-Z-]*>/.test(trimmed) && /<\/[a-zA-Z]/.test(trimmed)) continue;
-    if (isNarrativeKorean(trimmed)) continue;
+    if (isNarrative(trimmed)) continue;
     const correction = detectCorrection(text);
     if (correction) {
       corrections.push(correction);
@@ -2404,7 +2417,7 @@ function extractCorrections(messages) {
   }
   return corrections;
 }
-function isNarrativeKorean(text) {
+function isNarrative(text) {
   const NARRATIVE_MARKERS = [
     /이유는/,
     // "the reason is..."
@@ -2457,9 +2470,9 @@ function detectCorrection(text) {
   const isAffirmation = AFFIRMATION_PATTERNS.some((p) => p.test(text));
   if (!isNegation && !isMust && !isWarn && !isAffirmation) return null;
   const categories = [isNegation, isMust, isWarn, isAffirmation].filter(Boolean).length;
-  const koreanRatio = (text.match(/[\uAC00-\uD7AF]/g) || []).length / Math.max(text.length, 1);
-  if (koreanRatio > 0.3 && categories < 2) {
-    if (text.length > 100) return null;
+  const latinRatio = (text.match(/[a-zA-Z]/g) || []).length / Math.max(text.length, 1);
+  if (latinRatio < 0.3 && categories < 2) {
+    if (text.length > 150) return null;
   }
   let prefix;
   if (isNegation) prefix = "NO";
@@ -2661,33 +2674,65 @@ var init_digest = __esm({
       /\binstead\b/i,
       /^no[,.\s!]/i,
       /\bavoid\b/i,
-      // Korean negation — require AI-directed imperative context:
-      // "X하지 마" (don't X) — must have a verb object before 지 마
+      // Korean negation — imperative corrections:
       /[을를은는도이가]\s*[가-힣]+지\s*마/,
-      // "X 하면 안 돼" (must not X) — conditional + prohibition
+      // "X하지 마" (don't X) with particle
       /하면\s*안\s*돼/,
-      // "X 쓰지 마" (don't use X) — explicit "don't use"
-      /쓰지\s*마/
+      // "X 하면 안 돼" (must not X)
+      /쓰지\s*마/,
+      // "쓰지 마" (don't use)
+      /그만/,
+      // "그만" (stop) — 그만해, 그만 좀
+      /[을를은는]\s*빼/,
+      // "X 빼" (remove X) with particle
+      /지워[줘]?|삭제해/,
+      // "지워/삭제해" (delete it) — not 지우고 (connective)
+      /[가-힣]+지\s*말고/,
+      // "X지 말고" (instead of X-ing)
+      /그거\s*아니/,
+      // "그거 아니야" (that's not right)
+      /ㄴㄴ|노노/,
+      // "ㄴㄴ/노노" (no no — internet-style)
+      /안\s*돼[^요]?\s*[!.]/
+      // "안 돼!" standalone prohibition
     ];
     AFFIRMATION_PATTERNS = [
       /\bshould\s+always\b/i,
       /\buse\s+\w+\s+instead\b/i,
-      // Korean affirmation — require directive context
-      /항상\s*[가-힣]+[해하]/
+      // Korean affirmation — directive commands:
+      /항상\s*[가-힣]+[해하]/,
       // "항상 X해" (always do X)
+      /[을를]\s*[가-힣]*해\s*줘/,
+      // "X를 해줘" (do X for me) — literal 해줘, not bare 줘
+      /으로\s*해/,
+      // "X으로 해" (do it as X) — literal 으로, not char class
+      /이렇게\s*해/
+      // "이렇게 해" (do it like this)
     ];
     MUST_PATTERNS = [
       /\bmust\b/i,
       /\brequired\b/i,
-      // Korean
-      /반드시/
+      // Korean — strong directives:
+      /반드시/,
+      // "반드시" (absolutely must)
+      /꼭\s*[가-힣]/,
+      // "꼭 X해" (definitely do X)
+      /무조건/,
+      // "무조건" (unconditionally)
+      /필수/
+      // "필수" (mandatory)
     ];
     WARN_PATTERNS = [
       /\bcareful\b/i,
       /\bwatch\s+out\b/i,
       /\bwarning\b/i,
-      // Korean
-      /주의/
+      // Korean — cautionary:
+      /주의/,
+      // "주의" (caution)
+      /조심/,
+      // "조심" (be careful)
+      /위험/
+      // "위험" (dangerous)
     ];
     MAX_FAILURES_PER_SESSION = 20;
     SOFT_ERROR_PATTERNS = [
@@ -2701,6 +2746,48 @@ var init_digest = __esm({
   }
 });
 
+// src/learn.ts
+var learn_exports = {};
+__export(learn_exports, {
+  learn: () => learn
+});
+function learn(brainRoot, opts) {
+  let prefix;
+  let keywords;
+  let source;
+  if (opts.prefix && opts.keywords && opts.keywords.length > 0) {
+    prefix = opts.prefix.toUpperCase();
+    if (!VALID_PREFIXES.has(prefix)) {
+      prefix = "DO";
+    }
+    keywords = opts.keywords.slice(0, 3).map((k) => k.toLowerCase().replace(/[\s\/\\\.,:;!?'"<>{}()\[\]]/g, ""));
+    source = "agent";
+  } else {
+    const corrections = extractCorrections([opts.text]);
+    if (corrections.length === 0) return null;
+    const c = corrections[0];
+    prefix = c.prefix;
+    keywords = c.keywords;
+    source = "regex";
+  }
+  if (keywords.length === 0) return null;
+  const pathSegment = `${prefix}_${keywords.slice(0, 3).join("_")}`;
+  const path = `cortex/${pathSegment}`;
+  growCandidate(brainRoot, path);
+  logEpisode(brainRoot, "learn", path, opts.text);
+  return { path, prefix, keywords, source };
+}
+var VALID_PREFIXES;
+var init_learn = __esm({
+  "src/learn.ts"() {
+    "use strict";
+    init_candidates();
+    init_episode();
+    init_digest();
+    VALID_PREFIXES = /* @__PURE__ */ new Set(["NO", "DO", "MUST", "WARN"]);
+  }
+});
+
 // src/outcome.ts
 var outcome_exports = {};
 __export(outcome_exports, {
@@ -3276,6 +3363,7 @@ __export(doctor_exports, {
 });
 import { existsSync as existsSync18, readFileSync as readFileSync11, readdirSync as readdirSync11 } from "fs";
 import { join as join19 } from "path";
+import { homedir } from "os";
 import { execSync as execSync4 } from "child_process";
 async function runDoctor(brainRoot) {
   let passed = 0, warnings = 0, failed = 0;
@@ -3336,33 +3424,49 @@ async function runDoctor(brainRoot) {
     }
   }
   console.log("\nClaude Code hooks");
-  const settingsPath = join19(process.cwd(), ".claude", "settings.local.json");
-  if (!existsSync18(settingsPath)) {
-    warn("No .claude/settings.local.json found", "hebbian claude install");
-  } else {
+  const localSettingsPath = join19(process.cwd(), ".claude", "settings.local.json");
+  const globalSettingsPath = join19(homedir(), ".claude", "settings.json");
+  let hasStop = false;
+  let hasStart = false;
+  let hookSource = "";
+  for (const settingsPath of [localSettingsPath, globalSettingsPath]) {
+    if (!existsSync18(settingsPath)) continue;
     try {
       const settings = JSON.parse(readFileSync11(settingsPath, "utf8"));
       const hooks = settings.hooks || {};
-      const hasStop = Object.entries(hooks).some(
-        ([event, entries]) => event === "Stop" && Array.isArray(entries) && entries.some(
-          (e) => typeof e === "object" && e !== null && "command" in e && typeof e.command === "string" && e.command.includes("hebbian digest")
-        )
-      );
-      const hasStart = Object.entries(hooks).some(
-        ([event, entries]) => event === "SessionStart" && Array.isArray(entries) && entries.some(
-          (e) => typeof e === "object" && e !== null && "command" in e && typeof e.command === "string" && e.command.includes("hebbian emit")
-        )
+      const findCommand = (event, keyword) => Object.entries(hooks).some(
+        ([ev, entries]) => ev === event && Array.isArray(entries) && entries.some((entry) => {
+          if (typeof entry !== "object" || entry === null) return false;
+          const e = entry;
+          if (typeof e.command === "string" && e.command.includes(keyword)) return true;
+          if (Array.isArray(e.hooks)) {
+            return e.hooks.some(
+              (h) => typeof h === "object" && h !== null && typeof h.command === "string" && h.command.includes(keyword)
+            );
+          }
+          return false;
+        })
       );
-      if (hasStop && hasStart) {
-        ok("SessionStart + Stop hooks installed");
-      } else {
-        if (!hasStart) warn("SessionStart hook missing", "hebbian claude install");
-        if (!hasStop) warn("Stop hook missing", "hebbian claude install");
+      if (!hasStop && findCommand("Stop", "hebbian digest")) {
+        hasStop = true;
+        hookSource = settingsPath === globalSettingsPath ? "global" : "local";
+      }
+      if (!hasStart && findCommand("SessionStart", "hebbian emit")) {
+        hasStart = true;
+        if (!hookSource) hookSource = settingsPath === globalSettingsPath ? "global" : "local";
       }
     } catch {
-      fail("Malformed .claude/settings.local.json", "hebbian claude install");
+      warn(`Malformed ${settingsPath === globalSettingsPath ? "~/.claude/settings.json" : ".claude/settings.local.json"}`, "Check JSON syntax");
     }
   }
+  if (hasStop && hasStart) {
+    ok(`SessionStart + Stop hooks installed (${hookSource})`);
+  } else if (!hasStop && !hasStart) {
+    warn("No hebbian hooks found (checked local + global)", "hebbian claude install");
+  } else {
+    if (!hasStart) warn("SessionStart hook missing", "hebbian claude install");
+    if (!hasStop) warn("Stop hook missing", "hebbian claude install");
+  }
   console.log("\nnpx resolution");
   try {
     const resolved = execSync4("which npx", { timeout: 3e3 }).toString().trim();
@@ -3696,9 +3800,10 @@ COMMANDS:
   inbox                           Process corrections inbox
   claude install|uninstall|status Manage Claude Code hooks
   digest [--transcript <path>]    Extract corrections from conversation
+  learn "<text>" [--prefix P]      Agent-driven learning (any language)
   candidates [promote]            List candidates or promote graduated ones
-  evolve [--dry-run]              LLM-powered brain evolution (Gemini)
-  evolve prune [--dry-run]        Pruning mode \u2014 remove stale/redundant neurons
+  evolve [--dry-run]              (optional) LLM-powered evolution (Gemini)
+  evolve prune [--dry-run]        (optional) Pruning mode \u2014 remove stale neurons
   session start|end               Capture/detect session outcomes
   sessions                        Show session outcome history
   doctor                          Self-diagnostic (hooks, brain, versions)
@@ -3716,7 +3821,7 @@ EXAMPLES:
   hebbian fire cortex/frontend/NO_console_log --brain ./my-brain
   hebbian emit claude --brain ./my-brain
   hebbian emit all
-  GEMINI_API_KEY=... hebbian evolve --dry-run
+  GEMINI_API_KEY=... hebbian evolve --dry-run   # optional \u2014 self-learning works without this
 `.trim();
 function readStdin() {
   return new Promise((resolve4) => {
@@ -3742,6 +3847,8 @@ async function main(argv) {
       days: { type: "string", short: "d" },
       port: { type: "string", short: "p" },
       transcript: { type: "string", short: "t" },
+      prefix: { type: "string" },
+      keywords: { type: "string", short: "k" },
       "dry-run": { type: "boolean" },
       global: { type: "boolean", short: "g" },
       agent: { type: "string", short: "a" },
@@ -3918,6 +4025,27 @@ async function main(argv) {
       }
       break;
     }
+    case "learn": {
+      const text = positionals.slice(1).join(" ");
+      if (!text) {
+        console.error('Usage: hebbian learn "correction text" [--prefix NO|DO|MUST|WARN] [--keywords "k1,k2,k3"]');
+        process.exit(1);
+      }
+      const { learn: learn2 } = await Promise.resolve().then(() => (init_learn(), learn_exports));
+      const prefixFlag = values.prefix;
+      const keywordsFlag = values.keywords;
+      const result = learn2(brainRoot, {
+        text,
+        prefix: prefixFlag,
+        keywords: keywordsFlag ? keywordsFlag.split(",").map((k) => k.trim()) : void 0
+      });
+      if (result) {
+        console.log(`\u{1F4DD} learned: ${result.path} (${result.source})`);
+      } else {
+        console.log("\u23ED\uFE0F no correction detected");
+      }
+      break;
+    }
     case "candidates": {
       const subCmd = positionals[1];
       const { listCandidates: listCandidates2, promoteCandidates: promoteCandidates2 } = await Promise.resolve().then(() => (init_candidates(), candidates_exports));