hebbian 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IISweetHeartII
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/Node.js-22+-339933?style=flat-square&logo=node.js" />
+  <img src="https://img.shields.io/badge/Dependencies-0-brightgreen?style=flat-square" />
+  <img src="https://img.shields.io/badge/Tests-120-blue?style=flat-square" />
+  <img src="https://img.shields.io/badge/MIT-green?style=flat-square" />
+</p>
+
+<p align="center"><a href="README.ko.md">한국어</a> · <a href="CHANGELOG.md">Changelog</a></p>
+
+# hebbian
+
+### *Folder-as-neuron brain for any AI agent.*
+
+> "Neurons that fire together, wire together." — Donald Hebb (1949)
+
+---
+
+## TL;DR
+
+**`mkdir` replaces system prompts.** Folders are neurons. Paths are sentences. Counter files are synaptic weights.
+
+```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
+```
+
+| Before | hebbian |
+|--------|------|
+| 1000-line prompts, manually edited | `mkdir` one folder |
+| 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 |
+
+---
+
+## Why "hebbian"?
+
+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.
+
+---
+
+## How It Works
+
+### Folder = Neuron. Path = Sentence.
+
+```
+brain/cortex/frontend/禁console_log/40.neuron
+```
+
+Read it: "Cortex > Frontend > Never use console.log. Reinforced 40 times."
+
+### 7-Region Subsumption Architecture
+
+```
+P0: brainstem    → Absolute laws (immutable, read-only)
+P1: limbic       → Emotion filters
+P2: hippocampus  → Memory, session restore
+P3: sensors      → Environment constraints
+P4: cortex       → Knowledge, skills (largest region)
+P5: ego          → Tone, personality
+P6: prefrontal   → Goals, projects
+
+Rule: Lower P always suppresses higher P.
+bomb.neuron in any region → cascade halt.
+```
+
+### File Types
+
+| File | Meaning | Biology |
+|------|---------|---------|
+| `N.neuron` | Excitatory counter (strength) | Synaptic weight |
+| `N.contra` | Inhibitory counter | Inhibitory synapse |
+| `dopamineN.neuron` | Reward signal | Dopamine |
+| `bomb.neuron` | Circuit breaker | Pain response |
+| `memoryN.neuron` | Episode recording | Long-term memory |
+| `*.dormant` | Inactive marker | Sleep pruning |
+| `.axon` | Cross-region link | Axon connection |
+
+---
+
+## CLI Reference
+
+```bash
+hebbian init <path>                     # Create brain with 7 regions
+hebbian emit <target> [--brain <path>]  # Compile rules
+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
+```
+
+### Emit Targets
+
+| Target | Output File |
+|--------|-------------|
+| `claude` | `CLAUDE.md` |
+| `cursor` | `.cursorrules` |
+| `gemini` | `.gemini/GEMINI.md` |
+| `copilot` | `.github/copilot-instructions.md` |
+| `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 |
+
+This keeps the token budget lean. 293 neurons → ~500 tokens at startup.
+
+---
+
+## Synaptic Consolidation
+
+When you `hebbian grow`, the system checks for similar existing neurons using Jaccard similarity:
+
+```bash
+hebbian grow cortex/frontend/禁console_logging --brain ./brain
+# → "禁console_logging" ≈ "禁console_log" (Jaccard ≥ 0.6)
+# → Fires existing neuron instead of creating duplicate
+```
+
+**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 Dependencies
+
+hebbian uses only Node.js built-in modules:
+
+- `node:fs` — filesystem operations
+- `node:path` — path handling
+- `node:util` — CLI argument parsing
+- `node:http` — REST API (planned)
+
+**Runtime dependencies: 0.** Matches the Go version's zero-dep philosophy, but with `npx` instant execution.
+
+---
+
+## Governance
+
+120 tests pass in ~850ms:
+
+- **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: 9 tests
+
+```bash
+node --test                           # Run all tests
+node --test test/governance.test.js   # Governance only
+```
+
+---
+
+## 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.
+
+---
+
+## License
+
+MIT

package/bin/hebbian.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+// hebbian — Folder-as-Neuron Brain for Any AI Agent
+//
+// "Neurons that fire together, wire together." — Donald Hebb (1949)
+//
+// USAGE:
+//   hebbian init <path>                     Create brain with 7 regions
+//   hebbian emit <target> [--brain <path>]  Compile rules (claude/cursor/gemini/copilot/generic/all)
+//   hebbian fire <neuron-path>              Increment neuron counter
+//   hebbian grow <neuron-path>              Create neuron (with merge detection)
+//   hebbian rollback <neuron-path>          Decrement counter (min=1)
+//   hebbian signal <type> <neuron-path>     Add dopamine/bomb/memory signal
+//   hebbian decay [--days N]                Mark inactive neurons dormant (default 30 days)
+//   hebbian watch [--brain <path>]          Watch for changes + auto-recompile
+//   hebbian diag                            Print brain diagnostics
+//   hebbian stats                           Print brain statistics
+
+import { parseArgs } from 'node:util';
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+
+const VERSION = '0.1.0';
+
+const HELP = `
+hebbian v${VERSION} — Folder-as-neuron brain for any AI agent.
+
+  "Neurons that fire together, wire together." — Donald Hebb (1949)
+
+USAGE:
+  hebbian <command> [options]
+
+COMMANDS:
+  init <path>                     Create brain with 7 regions
+  emit <target> [--brain <path>]  Compile rules (claude/cursor/gemini/copilot/generic/all)
+  fire <neuron-path>              Increment neuron counter (+1)
+  grow <neuron-path>              Create neuron (with merge detection)
+  rollback <neuron-path>          Decrement neuron counter (min=1)
+  signal <type> <neuron-path>     Add signal (dopamine/bomb/memory)
+  decay [--days N]                Mark inactive neurons dormant (default 30)
+  dedup                           Batch merge similar neurons (Jaccard >= 0.6)
+  snapshot                        Git commit current brain state
+  watch                           Watch for changes + auto-recompile
+  diag                            Print brain diagnostics
+  stats                           Print brain statistics
+
+OPTIONS:
+  --brain <path>   Brain directory (default: $HEBBIAN_BRAIN or ./brain)
+  --help, -h       Show this help
+  --version, -v    Show version
+
+EXAMPLES:
+  hebbian init ./my-brain
+  hebbian grow cortex/frontend/禁console_log --brain ./my-brain
+  hebbian fire cortex/frontend/禁console_log --brain ./my-brain
+  hebbian emit claude --brain ./my-brain
+  hebbian emit all
+`.trim();
+
+/** Resolve brain root path from --brain flag, env var, or defaults */
+function resolveBrainRoot(brainFlag) {
+	if (brainFlag) return resolve(brainFlag);
+	if (process.env.HEBBIAN_BRAIN) return resolve(process.env.HEBBIAN_BRAIN);
+	if (existsSync(resolve('./brain'))) return resolve('./brain');
+	return resolve(process.env.HOME || '~', 'hebbian', 'brain');
+}
+
+async function main(argv) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		options: {
+			brain: { type: 'string', short: 'b' },
+			days: { type: 'string', short: 'd' },
+			port: { type: 'string', short: 'p' },
+			help: { type: 'boolean', short: 'h' },
+			version: { type: 'boolean', short: 'v' },
+		},
+		allowPositionals: true,
+		strict: false,
+	});
+
+	if (values.version) {
+		console.log(`hebbian v${VERSION}`);
+		return;
+	}
+
+	const command = positionals[0];
+
+	if (values.help || !command) {
+		console.log(HELP);
+		return;
+	}
+
+	const brainRoot = resolveBrainRoot(values.brain);
+
+	switch (command) {
+		case 'init': {
+			const target = positionals[1];
+			if (!target) {
+				console.error('Usage: hebbian init <path>');
+				process.exit(1);
+			}
+			const { initBrain } = await import('../lib/init.js');
+			await initBrain(resolve(target));
+			break;
+		}
+		case 'emit': {
+			const target = positionals[1];
+			if (!target) {
+				console.error('Usage: hebbian emit <target> (claude/cursor/gemini/copilot/generic/all)');
+				process.exit(1);
+			}
+			const { emitToTarget } = await import('../lib/emit.js');
+			await emitToTarget(brainRoot, target);
+			break;
+		}
+		case 'fire': {
+			const neuronPath = positionals[1];
+			if (!neuronPath) {
+				console.error('Usage: hebbian fire <neuron-path>');
+				process.exit(1);
+			}
+			const { fireNeuron } = await import('../lib/fire.js');
+			await fireNeuron(brainRoot, neuronPath);
+			break;
+		}
+		case 'grow': {
+			const neuronPath = positionals[1];
+			if (!neuronPath) {
+				console.error('Usage: hebbian grow <neuron-path>');
+				process.exit(1);
+			}
+			const { growNeuron } = await import('../lib/grow.js');
+			await growNeuron(brainRoot, neuronPath);
+			break;
+		}
+		case 'rollback': {
+			const neuronPath = positionals[1];
+			if (!neuronPath) {
+				console.error('Usage: hebbian rollback <neuron-path>');
+				process.exit(1);
+			}
+			const { rollbackNeuron } = await import('../lib/rollback.js');
+			await rollbackNeuron(brainRoot, neuronPath);
+			break;
+		}
+		case 'signal': {
+			const signalType = positionals[1];
+			const neuronPath = positionals[2];
+			if (!signalType || !neuronPath) {
+				console.error('Usage: hebbian signal <type> <neuron-path>  (type: dopamine/bomb/memory)');
+				process.exit(1);
+			}
+			const { signalNeuron } = await import('../lib/signal.js');
+			await signalNeuron(brainRoot, neuronPath, signalType);
+			break;
+		}
+		case 'decay': {
+			const days = values.days ? parseInt(values.days, 10) : 30;
+			const { runDecay } = await import('../lib/decay.js');
+			await runDecay(brainRoot, days);
+			break;
+		}
+		case 'dedup': {
+			const { runDedup } = await import('../lib/dedup.js');
+			runDedup(brainRoot);
+			break;
+		}
+		case 'snapshot': {
+			const { gitSnapshot } = await import('../lib/snapshot.js');
+			gitSnapshot(brainRoot);
+			break;
+		}
+		case 'watch': {
+			const { startWatch } = await import('../lib/watch.js');
+			await startWatch(brainRoot);
+			break;
+		}
+		case 'diag':
+		case 'stats': {
+			const { scanBrain } = await import('../lib/scanner.js');
+			const { runSubsumption } = await import('../lib/subsumption.js');
+			const brain = scanBrain(brainRoot);
+			const result = runSubsumption(brain);
+			const { printDiag } = await import('../lib/emit.js');
+			printDiag(brain, result);
+			break;
+		}
+		default:
+			console.error(`Unknown command: ${command}`);
+			console.log(HELP);
+			process.exit(1);
+	}
+}
+
+main(process.argv.slice(2)).catch((err) => {
+	console.error(err.message);
+	process.exit(1);
+});

package/lib/constants.js

@@ -0,0 +1,83 @@
+// hebbian — Constants & Configuration
+//
+// AXIOMS:
+//   1. Folder = Neuron (name is meaning, depth is specificity)
+//   2. File = Firing Trace (N.neuron = counter, dopamineN = reward, bomb = pain)
+//   3. Path = Sentence (brain/cortex/quality/no_hardcoded → "cortex > quality > no_hardcoded")
+//   4. Counter = Activation (higher = stronger/myelinated path)
+//   5. AI writes back (counter increment = experience growth)
+
+/** Ordered list of brain regions by subsumption priority (P0 → P6) */
+export const REGIONS = [
+	'brainstem',
+	'limbic',
+	'hippocampus',
+	'sensors',
+	'cortex',
+	'ego',
+	'prefrontal',
+];
+
+/** Region → priority index (lower = higher priority) */
+export const REGION_PRIORITY = /** @type {Record<string, number>} */ ({
+	brainstem: 0,
+	limbic: 1,
+	hippocampus: 2,
+	sensors: 3,
+	cortex: 4,
+	ego: 5,
+	prefrontal: 6,
+});
+
+/** Region display icons */
+export const REGION_ICONS = /** @type {Record<string, string>} */ ({
+	brainstem: '\u{1F6E1}\uFE0F',   // 🛡️
+	limbic: '\u{1F493}',             // 💓
+	hippocampus: '\u{1F4DD}',        // 📝
+	sensors: '\u{1F441}\uFE0F',      // 👁️
+	cortex: '\u{1F9E0}',             // 🧠
+	ego: '\u{1F3AD}',                // 🎭
+	prefrontal: '\u{1F3AF}',         // 🎯
+});
+
+/** Region Korean descriptions */
+export const REGION_KO = /** @type {Record<string, string>} */ ({
+	brainstem: '양심/본능',
+	limbic: '감정 필터',
+	hippocampus: '기록/기억',
+	sensors: '환경 제약',
+	cortex: '지식/기술',
+	ego: '성향/톤',
+	prefrontal: '목표/계획',
+});
+
+/** Minimum counter value for a neuron to appear in emitted output */
+export const EMIT_THRESHOLD = 5;
+
+/** Days a new neuron gets spotlight coverage regardless of counter */
+export const SPOTLIGHT_DAYS = 7;
+
+/** Jaccard similarity threshold for neuron merge detection */
+export const JACCARD_THRESHOLD = 0.6;
+
+/** Default number of days before marking a neuron dormant */
+export const DECAY_DAYS = 30;
+
+/** Maximum recursion depth when walking brain directories */
+export const MAX_DEPTH = 6;
+
+/** Emit target → file path mapping */
+export const EMIT_TARGETS = /** @type {Record<string, string>} */ ({
+	gemini: '.gemini/GEMINI.md',
+	cursor: '.cursorrules',
+	claude: 'CLAUDE.md',
+	copilot: '.github/copilot-instructions.md',
+	generic: '.neuronrc',
+});
+
+/** Valid signal types */
+export const SIGNAL_TYPES = ['dopamine', 'bomb', 'memory'];
+
+/** Emit markers for injection into existing files */
+export const MARKER_START = '<!-- HEBBIAN:START -->';
+export const MARKER_END = '<!-- HEBBIAN:END -->';

package/lib/decay.js

@@ -0,0 +1,100 @@
+// hebbian — Decay (dormancy sweep)
+//
+// Neurons that haven't been touched in N days are marked dormant.
+// Dormancy = *.dormant file in the neuron directory.
+// Dormant neurons are excluded from emission and activation counts.
+//
+// "Most neurons die. Only the repeatedly fired ones survive." — Natural selection on OS.
+
+import { readdirSync, statSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { REGIONS, MAX_DEPTH } from './constants.js';
+
+/**
+ * Sweep the brain and mark inactive neurons as dormant.
+ *
+ * @param {string} brainRoot - Absolute path to brain root
+ * @param {number} days - Number of days of inactivity before dormancy
+ * @returns {{ scanned: number, decayed: number }}
+ */
+export function runDecay(brainRoot, days) {
+	const threshold = Date.now() - days * 24 * 60 * 60 * 1000;
+	let scanned = 0;
+	let decayed = 0;
+
+	for (const regionName of REGIONS) {
+		const regionPath = join(brainRoot, regionName);
+		if (!existsSync(regionPath)) continue;
+		const result = decayWalk(regionPath, threshold, 0);
+		scanned += result.scanned;
+		decayed += result.decayed;
+	}
+
+	console.log(`\u{1F4A4} decay: scanned ${scanned} neurons, decayed ${decayed} (>${days} days inactive)`);
+	return { scanned, decayed };
+}
+
+/**
+ * @param {string} dir
+ * @param {number} threshold - Timestamp threshold
+ * @param {number} depth
+ * @returns {{ scanned: number, decayed: number }}
+ */
+function decayWalk(dir, threshold, depth) {
+	if (depth > MAX_DEPTH) return { scanned: 0, decayed: 0 };
+
+	let scanned = 0;
+	let decayed = 0;
+	let entries;
+
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return { scanned: 0, decayed: 0 };
+	}
+
+	// Check if this directory is a neuron (has .neuron files)
+	let hasNeuronFile = false;
+	let isDormant = false;
+	let latestMod = 0;
+
+	for (const entry of entries) {
+		if (entry.isFile()) {
+			if (entry.name.endsWith('.neuron')) {
+				hasNeuronFile = true;
+				try {
+					const st = statSync(join(dir, entry.name));
+					if (st.mtimeMs > latestMod) latestMod = st.mtimeMs;
+				} catch {}
+			}
+			if (entry.name.endsWith('.dormant')) {
+				isDormant = true;
+			}
+		}
+	}
+
+	if (hasNeuronFile) {
+		scanned++;
+		if (!isDormant && latestMod < threshold) {
+			const age = Math.floor((Date.now() - latestMod) / (24 * 60 * 60 * 1000));
+			writeFileSync(
+				join(dir, 'decay.dormant'),
+				`Dormant since ${new Date().toISOString()} (${age} days inactive)`,
+				'utf8',
+			);
+			decayed++;
+		}
+	}
+
+	// Recurse
+	for (const entry of entries) {
+		if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
+		if (entry.isDirectory()) {
+			const sub = decayWalk(join(dir, entry.name), threshold, depth + 1);
+			scanned += sub.scanned;
+			decayed += sub.decayed;
+		}
+	}
+
+	return { scanned, decayed };
+}

package/lib/dedup.js

@@ -0,0 +1,66 @@
+// hebbian — Batch Deduplication
+//
+// Scans all neurons in a region and merges duplicates via Jaccard similarity.
+// When a match is found (>= threshold), fires the higher-counter neuron
+// and marks the lower-counter one dormant.
+
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { JACCARD_THRESHOLD } from './constants.js';
+import { tokenize, jaccardSimilarity } from './similarity.js';
+import { fireNeuron } from './fire.js';
+import { scanBrain } from './scanner.js';
+
+/**
+ * Run batch deduplication across all regions.
+ * @param {string} brainRoot
+ * @returns {{ scanned: number, merged: number }}
+ */
+export function runDedup(brainRoot) {
+	const brain = scanBrain(brainRoot);
+	let scanned = 0;
+	let merged = 0;
+
+	for (const region of brain.regions) {
+		const neurons = region.neurons.filter((n) => !n.isDormant);
+		scanned += neurons.length;
+
+		// O(n^2) pairwise comparison within each region
+		const consumed = new Set();
+		for (let i = 0; i < neurons.length; i++) {
+			if (consumed.has(i)) continue;
+			const tokensI = tokenize(neurons[i].name);
+
+			for (let j = i + 1; j < neurons.length; j++) {
+				if (consumed.has(j)) continue;
+				const tokensJ = tokenize(neurons[j].name);
+				const sim = jaccardSimilarity(tokensI, tokensJ);
+
+				if (sim >= JACCARD_THRESHOLD) {
+					// Keep the one with higher counter, mark other dormant
+					const [keep, drop] = neurons[i].counter >= neurons[j].counter
+						? [neurons[i], neurons[j]]
+						: [neurons[j], neurons[i]];
+
+					// Fire the keeper to absorb the dropped counter
+					const relKeep = `${region.name}/${keep.path}`;
+					fireNeuron(brainRoot, relKeep);
+
+					// Mark the dropped neuron dormant
+					writeFileSync(
+						join(drop.fullPath, 'dedup.dormant'),
+						`Merged into ${keep.path} on ${new Date().toISOString()}`,
+						'utf8',
+					);
+
+					consumed.add(neurons[i] === drop ? i : j);
+					merged++;
+					console.log(`\u{1F500} merged: "${drop.path}" → "${keep.path}" (sim=${sim.toFixed(2)})`);
+				}
+			}
+		}
+	}
+
+	console.log(`\u{1F9F9} dedup: scanned ${scanned} neurons, merged ${merged}`);
+	return { scanned, merged };
+}