hebbian 0.3.4 → 0.5.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-134-blue?style=flat-square" />
+  <img src="https://img.shields.io/badge/Tests-277-blue?style=flat-square" />
   <img src="https://img.shields.io/badge/MIT-green?style=flat-square" />
 </p>
 
@@ -10,12 +10,47 @@
 
 # hebbian
 
-### *Folder-as-neuron brain for any AI agent.*
+### *Folder-as-neuron brain for any AI agent. Self-evolving.*
 
 > "Neurons that fire together, wire together." — Donald Hebb (1949)
 
 ---
 
+## The 2-minute demo
+
+```bash
+# 1. Install and init a brain
+npm install -g hebbian
+hebbian init ./brain
+hebbian claude install       # attach to Claude Code (hooks)
+
+# 2. Start a Claude Code session
+claude
+```
+
+During the session, correct Claude once:
+
+```
+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:
+hebbian candidates
+#   ░░█  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
+
+# 5. Next session — Claude sees the rule in CLAUDE.md:
+#   ❌ NO console.log → use logger utility
+```
+
+**That's it.** One correction, hebbian learns. Three confirmations, it becomes permanent.
+
+---
+
 ## TL;DR
 
 **`mkdir` replaces system prompts.** Folders are neurons. Paths are sentences. Counter files are synaptic weights.
@@ -23,9 +58,8 @@
 ```bash
 npx hebbian init ./brain
 npx hebbian grow brainstem/禁fallback --brain ./brain
-npx hebbian fire brainstem/禁fallback --brain ./brain
 npx hebbian emit claude --brain ./brain    # → CLAUDE.md
-npx hebbian emit all --brain ./brain       # → All AI formats at once
+npx hebbian evolve --dry-run               # → LLM proposes brain mutations
 ```
 
 | Before | hebbian |
@@ -34,25 +68,43 @@ npx hebbian emit all --brain ./brain       # → All AI formats at once
 | Vector DB $70/mo | **$0** (folders = DB) |
 | Switch AI → full migration | `cp -r brain/` — 1 second |
 | Rule violation → wishful thinking | `bomb.neuron` → **cascade halt** |
-| Rules managed by humans | Correction → auto neuron growth |
+| Rules accumulate forever | Candidates decay if not confirmed |
 
 ---
 
-## Why "hebbian"?
+## How It Works
 
-Donald Hebb's 1949 principle: **neurons that fire together, wire together.** Repeated corrections strengthen synaptic pathways. That's exactly what this tool does — every `hebbian fire` increments a counter, and only frequently-fired neurons survive. Natural selection on your filesystem.
+### Architecture
 
----
+```
+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
+```
 
-## How It Works
+### Candidate Staging (immune system)
 
-### Folder = Neuron. Path = Sentence.
+New neurons don't go straight into the brain. They land in `_candidates/` first:
 
 ```
-brain/cortex/frontend/禁console_log/40.neuron
+brain/cortex/_candidates/NO_console_log/1.neuron   ← 1st correction
+brain/cortex/_candidates/NO_console_log/2.neuron   ← 2nd correction
+brain/cortex/_candidates/NO_console_log/3.neuron   ← promoted!
+brain/cortex/NO_console_log/3.neuron               ← permanent
 ```
 
-Read it: "Cortex > Frontend > Never use console.log. Reinforced 40 times."
+- Counter >= 3 → graduates to permanent region
+- 14 days without a fire → decays (removed)
+- This prevents hallucinations and one-off corrections from permanently changing behavior
 
 ### 7-Region Subsumption Architecture
 
@@ -79,23 +131,75 @@ bomb.neuron in any region → cascade halt.
 | `bomb.neuron` | Circuit breaker | Pain response |
 | `memoryN.neuron` | Episode recording | Long-term memory |
 | `*.dormant` | Inactive marker | Sleep pruning |
-| `.axon` | Cross-region link | Axon connection |
+
+---
+
+## Claude Code Integration
+
+One command to set up:
+
+```bash
+hebbian claude install
+```
+
+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 |
+
+Check status anytime:
+
+```bash
+hebbian claude status
+hebbian doctor       # full diagnostic
+```
+
+---
+
+## LLM Evolution
+
+```bash
+GEMINI_API_KEY=... hebbian evolve --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).
 
 ---
 
 ## CLI Reference
 
 ```bash
+# Brain management
 hebbian init <path>                     # Create brain with 7 regions
-hebbian emit <target> [--brain <path>]  # Compile rules
+hebbian doctor                          # Self-diagnostic (hooks, versions, brain)
+hebbian diag                            # Brain diagnostics
+hebbian stats                           # Brain statistics
+
+# Neuron operations
+hebbian grow <neuron-path>              # Create neuron (merge detection via Jaccard)
 hebbian fire <neuron-path>              # Increment counter (+1)
-hebbian grow <neuron-path>              # Create neuron (with merge detection)
 hebbian rollback <neuron-path>          # Decrement counter (min=1)
 hebbian signal <type> <neuron-path>     # Add signal (dopamine/bomb/memory)
 hebbian decay [--days N]                # Mark inactive neurons dormant
-hebbian watch                           # Auto-recompile on changes
-hebbian diag                            # Brain diagnostics
-hebbian stats                           # Brain statistics
+hebbian dedup                           # Batch merge similar neurons
+
+# Candidates
+hebbian candidates                      # List pending candidates
+hebbian candidates promote              # Promote graduated, decay stale
+
+# Emit / compile
+hebbian emit <target> [--brain <path>]  # claude/cursor/gemini/copilot/generic/all
+
+# Claude Code
+hebbian claude install|uninstall|status
+hebbian digest [--transcript <path>]
+
+# Evolution
+GEMINI_API_KEY=... hebbian evolve [--dry-run]
 ```
 
 ### Emit Targets
@@ -109,54 +213,40 @@ hebbian stats                           # Brain statistics
 | `generic` | `.neuronrc` |
 | `all` | All of the above |
 
-### Environment Variables
-
-| Variable | Purpose | Default |
-|----------|---------|---------|
-| `HEBBIAN_BRAIN` | Brain directory path | `./brain` |
-
 ---
 
-## 3-Tier Emission
-
-hebbian compiles your brain into 3 tiers:
-
-| Tier | File | Tokens | When |
-|------|------|--------|------|
-| 1 | Target file (CLAUDE.md, etc.) | ~500 | Auto-loaded by AI |
-| 2 | `brain/_index.md` | ~1000 | AI reads at session start |
-| 3 | `brain/{region}/_rules.md` | Variable | AI reads on demand |
+## Compared to
 
-This keeps the token budget lean. 293 neurons → ~500 tokens at startup.
+| Feature | .cursorrules / CLAUDE.md | Mem0 / MemOS | hebbian |
+|---------|--------------------------|-------------|------|
+| Self-learning | ❌ manual | ✅ vector DB | ✅ filesystem |
+| Infrastructure | $0 | $$$ | **$0** |
+| Switch AI | Manual migration | Full re-setup | **`cp -r brain/`** |
+| Immutable guardrails | None | None | **brainstem + bomb** |
+| False-positive protection | None | None | **candidate staging** |
+| Audit trail | Text file | DB logs | **`ls -R` = full history** |
+| Runtime deps | N/A | Many | **0** |
+| Offline | ✅ | ❌ | **✅** |
 
 ---
 
-## Synaptic Consolidation
-
-When you `hebbian grow`, the system checks for similar existing neurons using Jaccard similarity:
+## Starter Brain Templates
 
 ```bash
-hebbian grow cortex/frontend/禁console_logging --brain ./brain
-# → "禁console_logging" ≈ "禁console_log" (Jaccard ≥ 0.6)
-# → Fires existing neuron instead of creating duplicate
+# TypeScript strict mode brain
+hebbian init ./brain
+hebbian grow brainstem/NO_any_type
+hebbian grow brainstem/NO_implicit_returns
+hebbian grow cortex/DO_strict_mode
+hebbian grow cortex/DO_explicit_types
+
+# Python best practices
+hebbian grow brainstem/NO_bare_except
+hebbian grow brainstem/NO_mutable_defaults
+hebbian grow cortex/DO_type_hints
+hebbian grow cortex/DO_dataclasses
 ```
 
-**Consolidation over duplication.** Hebbian principle in action.
-
----
-
-## Compared to
-
-| Feature | .cursorrules | Mem0/Letta | hebbian |
-|---------|-------------|------------|------|
-| 1000+ rules | Token overflow | Vector DB | Folder tree |
-| Infrastructure | $0 | $$$$ | **$0** |
-| Switch AI | Manual migration | Full re-setup | **`cp -r brain/`** |
-| Self-growth | Manual | Bot-based | **Counter-based** |
-| Immutable guardrails | None | None | **brainstem + bomb** |
-| Audit trail | Hidden | DB logs | **`ls -R` = full history** |
-| Runtime deps | N/A | Many | **0** |
-
 ---
 
 ## Zero Runtime Dependencies
@@ -166,35 +256,30 @@ Written in **TypeScript 6.0**, built with tsup, tested with vitest.
 - `node:fs` — filesystem operations
 - `node:path` — path handling
 - `node:util` — CLI argument parsing
-- `node:http` — REST API (planned)
+- `node:http` — REST API
+- `node:https` / `fetch()` — LLM API calls (Node 22 built-in)
 
-**Runtime dependencies: 0.** Dev dependencies (typescript, tsup, vitest) are build-time only. Published package contains only compiled JS + type declarations.
+**Runtime dependencies: 0.**
 
 ---
 
 ## Governance
 
-134 tests pass in ~2s:
+277 tests pass in ~10s:
 
-- **SCC** (Subsumption Cascade Correctness): 17/17 = **100%**
-- **MLA** (Memory Lifecycle Accuracy): 15/15 = **100%**
-- Scanner: 15 tests
-- Lifecycle: 18 tests
-- Emit: 16 tests
-- Similarity: 12 tests
-- CLI E2E: 21 tests
-- Dedup: 3 tests
+- **SCC** (Subsumption Cascade Correctness): 100%
+- **MLA** (Memory Lifecycle Accuracy): 100%
+- Candidates, Evolve, Digest, Hooks, Scanner, Similarity...
 
 ```bash
-npm test                              # Run all tests
-npx vitest run test/governance.test.ts  # Governance only
+npm test
 ```
 
 ---
 
 ## Inspired By
 
-[NeuronFS](https://github.com/rhino-acoustic/NeuronFS) — the original Go implementation that proved folders can be neurons. hebbian is a JavaScript reimagination, designed for the npm ecosystem and zero-dependency operation.
+[NeuronFS](https://github.com/rhino-acoustic/NeuronFS) — the original Go implementation that proved folders can be neurons. hebbian is a TypeScript reimagination, designed for the npm ecosystem and zero-dependency operation.
 
 ---