hebbian 0.1.0

package/lib/scanner.js

@@ -0,0 +1,227 @@
+// hebbian — Brain Filesystem Scanner
+//
+// Walks the brain directory tree and builds a structured representation.
+// Folders = neurons. Files = firing traces. Paths = sentences.
+//
+// Scan order follows subsumption priority (P0 brainstem → P6 prefrontal).
+// Only recognizes the 7 canonical region names at the top level.
+
+import { readdirSync, statSync, readFileSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { REGIONS, REGION_PRIORITY, MAX_DEPTH } from './constants.js';
+
+/**
+ * @typedef {object} Neuron
+ * @property {string} name       - Folder name (leaf)
+ * @property {string} path       - Relative path from region root
+ * @property {string} fullPath   - Absolute path on disk
+ * @property {number} counter    - Excitatory counter (from N.neuron)
+ * @property {number} contra     - Inhibitory counter (from N.contra)
+ * @property {number} dopamine   - Reward counter (from dopamineN.neuron)
+ * @property {number} intensity  - Net activation: counter - contra + dopamine
+ * @property {number} polarity   - Net / total, range -1.0 to +1.0
+ * @property {boolean} hasBomb   - bomb.neuron exists (circuit breaker)
+ * @property {boolean} hasMemory - memoryN.neuron exists
+ * @property {boolean} isDormant - *.dormant file exists
+ * @property {number} depth      - Depth within region
+ * @property {Date} modTime      - Most recent .neuron file modification time
+ */
+
+/**
+ * @typedef {object} Region
+ * @property {string} name
+ * @property {number} priority
+ * @property {string} path       - Absolute path to region directory
+ * @property {Neuron[]} neurons
+ * @property {string[]} axons    - Cross-region connections
+ * @property {boolean} hasBomb   - Any neuron in region has bomb
+ */
+
+/**
+ * @typedef {object} Brain
+ * @property {string} root
+ * @property {Region[]} regions
+ */
+
+/**
+ * Scan a brain directory and return all regions with their neurons.
+ * @param {string} brainRoot - Absolute path to brain root directory
+ * @returns {Brain}
+ */
+export function scanBrain(brainRoot) {
+	/** @type {Region[]} */
+	const regions = [];
+
+	for (const regionName of REGIONS) {
+		const regionPath = join(brainRoot, regionName);
+		if (!existsSync(regionPath)) {
+			regions.push({
+				name: regionName,
+				priority: REGION_PRIORITY[regionName],
+				path: regionPath,
+				neurons: [],
+				axons: [],
+				hasBomb: false,
+			});
+			continue;
+		}
+
+		const neurons = walkRegion(regionPath, regionPath, 0);
+		const axons = readAxons(regionPath);
+		const hasBomb = neurons.some((n) => n.hasBomb);
+
+		regions.push({
+			name: regionName,
+			priority: REGION_PRIORITY[regionName],
+			path: regionPath,
+			neurons,
+			axons,
+			hasBomb,
+		});
+	}
+
+	return { root: brainRoot, regions };
+}
+
+/**
+ * Recursively walk a region directory and collect neurons.
+ * A neuron is any directory that contains at least one trace file
+ * (*.neuron, *.contra, *.dormant, bomb.neuron).
+ *
+ * @param {string} dir - Current directory to scan
+ * @param {string} regionRoot - Root of the region (for relative paths)
+ * @param {number} depth - Current recursion depth
+ * @returns {Neuron[]}
+ */
+function walkRegion(dir, regionRoot, depth) {
+	if (depth > MAX_DEPTH) return [];
+
+	/** @type {Neuron[]} */
+	const neurons = [];
+	let entries;
+
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+
+	// Parse trace files in this directory
+	let counter = 0;
+	let contra = 0;
+	let dopamine = 0;
+	let hasBomb = false;
+	let hasMemory = false;
+	let isDormant = false;
+	let modTime = new Date(0);
+	let hasTraceFile = false;
+
+	for (const entry of entries) {
+		if (entry.name.startsWith('_')) continue;
+
+		if (entry.isFile()) {
+			const name = entry.name;
+
+			// N.neuron — excitatory counter
+			if (name.endsWith('.neuron') && !name.startsWith('dopamine') && !name.startsWith('memory') && name !== 'bomb.neuron') {
+				const n = parseInt(name, 10);
+				if (!isNaN(n) && n > counter) {
+					counter = n;
+					hasTraceFile = true;
+					try {
+						const st = statSync(join(dir, name));
+						if (st.mtime > modTime) modTime = st.mtime;
+					} catch {}
+				}
+			}
+
+			// N.contra — inhibitory counter
+			if (name.endsWith('.contra')) {
+				const n = parseInt(name, 10);
+				if (!isNaN(n) && n > contra) {
+					contra = n;
+					hasTraceFile = true;
+				}
+			}
+
+			// dopamineN.neuron — reward signal
+			if (name.startsWith('dopamine') && name.endsWith('.neuron')) {
+				const n = parseInt(name.replace('dopamine', ''), 10);
+				if (!isNaN(n) && n > dopamine) {
+					dopamine = n;
+					hasTraceFile = true;
+				}
+			}
+
+			// bomb.neuron — circuit breaker
+			if (name === 'bomb.neuron') {
+				hasBomb = true;
+				hasTraceFile = true;
+			}
+
+			// memoryN.neuron — memory signal
+			if (name.startsWith('memory') && name.endsWith('.neuron')) {
+				hasMemory = true;
+				hasTraceFile = true;
+			}
+
+			// *.dormant — dormancy marker
+			if (name.endsWith('.dormant')) {
+				isDormant = true;
+				hasTraceFile = true;
+			}
+		}
+	}
+
+	// If this directory has trace files, it's a neuron
+	if (hasTraceFile) {
+		const relPath = relative(regionRoot, dir) || '.';
+		const folderName = dir.split(sep).pop() || '';
+		const total = counter + contra + dopamine;
+		const intensity = counter - contra + dopamine;
+		const polarity = total > 0 ? intensity / total : 0;
+
+		neurons.push({
+			name: folderName,
+			path: relPath,
+			fullPath: dir,
+			counter,
+			contra,
+			dopamine,
+			intensity,
+			polarity: Math.round(polarity * 100) / 100,
+			hasBomb,
+			hasMemory,
+			isDormant,
+			depth,
+			modTime,
+		});
+	}
+
+	// Recurse into subdirectories
+	for (const entry of entries) {
+		if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
+		if (entry.isDirectory()) {
+			const subNeurons = walkRegion(join(dir, entry.name), regionRoot, depth + 1);
+			neurons.push(...subNeurons);
+		}
+	}
+
+	return neurons;
+}
+
+/**
+ * Read .axon file from a region directory.
+ * @param {string} regionPath
+ * @returns {string[]}
+ */
+function readAxons(regionPath) {
+	const axonPath = join(regionPath, '.axon');
+	if (!existsSync(axonPath)) return [];
+	try {
+		const content = readFileSync(axonPath, 'utf8').trim();
+		return content.split(/[\n,]+/).map((s) => s.trim()).filter(Boolean);
+	} catch {
+		return [];
+	}
+}

package/lib/signal.js

@@ -0,0 +1,68 @@
+// hebbian — Signal Neuron (dopamine / bomb / memory)
+//
+// Signals are additional trace files placed in a neuron directory:
+//   dopamineN.neuron — reward signal (positive reinforcement)
+//   bomb.neuron      — circuit breaker (halts downstream regions)
+//   memoryN.neuron   — memory marker (episodic recording)
+
+import { writeFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { SIGNAL_TYPES } from './constants.js';
+
+/**
+ * Add a signal to a neuron.
+ *
+ * @param {string} brainRoot - Absolute path to brain root
+ * @param {string} neuronPath - Relative path
+ * @param {string} signalType - One of: dopamine, bomb, memory
+ * @throws {Error} If signal type is invalid or neuron doesn't exist
+ */
+export function signalNeuron(brainRoot, neuronPath, signalType) {
+	if (!SIGNAL_TYPES.includes(signalType)) {
+		throw new Error(`Invalid signal type: ${signalType}. Valid: ${SIGNAL_TYPES.join(', ')}`);
+	}
+
+	const fullPath = join(brainRoot, neuronPath);
+	if (!existsSync(fullPath)) {
+		throw new Error(`Neuron not found: ${neuronPath}`);
+	}
+
+	switch (signalType) {
+		case 'bomb': {
+			writeFileSync(join(fullPath, 'bomb.neuron'), '', 'utf8');
+			console.log(`\u{1F4A3} bomb planted: ${neuronPath}`);
+			break;
+		}
+		case 'dopamine': {
+			const level = getNextSignalLevel(fullPath, 'dopamine');
+			writeFileSync(join(fullPath, `dopamine${level}.neuron`), '', 'utf8');
+			console.log(`\u{1F7E2} dopamine +${level}: ${neuronPath}`);
+			break;
+		}
+		case 'memory': {
+			const level = getNextSignalLevel(fullPath, 'memory');
+			writeFileSync(join(fullPath, `memory${level}.neuron`), '', 'utf8');
+			console.log(`\u{1F4BE} memory +${level}: ${neuronPath}`);
+			break;
+		}
+	}
+}
+
+/**
+ * Get the next signal level (current max + 1).
+ * @param {string} dir
+ * @param {string} prefix - "dopamine" or "memory"
+ * @returns {number}
+ */
+function getNextSignalLevel(dir, prefix) {
+	let max = 0;
+	try {
+		for (const entry of readdirSync(dir)) {
+			if (entry.startsWith(prefix) && entry.endsWith('.neuron')) {
+				const n = parseInt(entry.replace(prefix, ''), 10);
+				if (!isNaN(n) && n > max) max = n;
+			}
+		}
+	} catch {}
+	return max + 1;
+}

package/lib/similarity.js

@@ -0,0 +1,62 @@
+// hebbian — Tokenizer, Stemmer, Jaccard Similarity
+//
+// Used by growNeuron() to detect similar existing neurons and merge
+// instead of duplicating. Implements synaptic consolidation.
+//
+// "Neurons that fire together, wire together." — if two folder names
+// express the same concept, fire the existing one instead of creating a duplicate.
+
+/**
+ * Tokenize a neuron name into stemmed words.
+ * Splits on underscores, hyphens, spaces, and CamelCase boundaries.
+ * @param {string} name
+ * @returns {string[]}
+ */
+export function tokenize(name) {
+	return name
+		.replace(/([a-z])([A-Z])/g, '$1_$2')   // camelCase → snake
+		.replace(/[_\-\s]+/g, ' ')              // normalize separators
+		.toLowerCase()
+		.split(' ')
+		.map(stem)
+		.filter((t) => t.length > 1);           // drop single chars
+}
+
+/**
+ * Simple suffix stemmer — removes common English suffixes.
+ * Not a full Porter stemmer, but sufficient for Jaccard comparison.
+ * @param {string} word
+ * @returns {string}
+ */
+export function stem(word) {
+	const suffixes = ['ing', 'tion', 'sion', 'ness', 'ment', 'able', 'ible', 'ful', 'less', 'ous', 'ive', 'ity', 'ies', 'ed', 'er', 'es', 'ly', 'al', 'en'];
+	for (const suffix of suffixes) {
+		if (word.length > suffix.length + 2 && word.endsWith(suffix)) {
+			return word.slice(0, -suffix.length);
+		}
+	}
+	return word;
+}
+
+/**
+ * Compute Jaccard similarity between two token sets.
+ * |A ∩ B| / |A ∪ B|
+ * @param {string[]} a
+ * @param {string[]} b
+ * @returns {number} 0.0 to 1.0
+ */
+export function jaccardSimilarity(a, b) {
+	if (a.length === 0 && b.length === 0) return 1.0;
+	if (a.length === 0 || b.length === 0) return 0.0;
+
+	const setA = new Set(a);
+	const setB = new Set(b);
+	let intersection = 0;
+
+	for (const item of setA) {
+		if (setB.has(item)) intersection++;
+	}
+
+	const union = new Set([...setA, ...setB]).size;
+	return intersection / union;
+}

package/lib/snapshot.js

@@ -0,0 +1,46 @@
+// hebbian — Git Snapshot
+//
+// Creates a git commit of the current brain state for audit trail.
+// Only commits if there are changes.
+
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Create a git snapshot of the brain directory.
+ * @param {string} brainRoot
+ * @returns {boolean} Whether a commit was created
+ */
+export function gitSnapshot(brainRoot) {
+	// Check if brain is inside a git repo
+	if (!existsSync(join(brainRoot, '.git'))) {
+		// Try parent directories
+		try {
+			execSync('git rev-parse --is-inside-work-tree', { cwd: brainRoot, stdio: 'pipe' });
+		} catch {
+			console.log('\u{26A0}\uFE0F  Not a git repository. Run `git init` in the brain directory first.');
+			return false;
+		}
+	}
+
+	try {
+		// Check for changes
+		const status = execSync('git status --porcelain .', { cwd: brainRoot, encoding: 'utf8' });
+		if (!status.trim()) {
+			console.log('\u{2705} No changes to snapshot.');
+			return false;
+		}
+
+		// Stage and commit
+		execSync('git add .', { cwd: brainRoot, stdio: 'pipe' });
+		const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+		execSync(`git commit -m "hebbian snapshot ${ts}"`, { cwd: brainRoot, stdio: 'pipe' });
+
+		console.log(`\u{1F4F8} snapshot: committed brain state at ${ts}`);
+		return true;
+	} catch (err) {
+		console.error(`\u{274C} snapshot failed: ${err.message}`);
+		return false;
+	}
+}

package/lib/subsumption.js

@@ -0,0 +1,77 @@
+// hebbian — Subsumption Cascade Engine
+//
+// Implements Brooks' subsumption architecture:
+//   - Lower priority (P0) always suppresses higher priority (P6)
+//   - bomb.neuron in any region halts all downstream regions
+//   - Dormant neurons are excluded from activation counts
+//
+// Cascade flow:
+//   P0 brainstem → P1 limbic → P2 hippocampus → P3 sensors → P4 cortex → P5 ego → P6 prefrontal
+//   If bomb at P(n), all P(n+1)→P6 are BLOCKED.
+
+/**
+ * @typedef {import('./scanner.js').Brain} Brain
+ * @typedef {import('./scanner.js').Region} Region
+ */
+
+/**
+ * @typedef {object} SubsumptionResult
+ * @property {Region[]} activeRegions   - Regions that passed the cascade
+ * @property {Region[]} blockedRegions  - Regions blocked by upstream bomb
+ * @property {string} bombSource        - Name of the region that triggered the bomb ("" if none)
+ * @property {number} firedNeurons      - Count of non-dormant neurons in active regions
+ * @property {number} totalNeurons      - Count of all neurons across all regions
+ * @property {number} totalCounter      - Sum of all counters in active, non-dormant neurons
+ */
+
+/**
+ * Run the subsumption cascade on a scanned brain.
+ *
+ * @param {Brain} brain
+ * @returns {SubsumptionResult}
+ */
+export function runSubsumption(brain) {
+	/** @type {Region[]} */
+	const activeRegions = [];
+	/** @type {Region[]} */
+	const blockedRegions = [];
+	let bombSource = '';
+	let firedNeurons = 0;
+	let totalNeurons = 0;
+	let totalCounter = 0;
+	let blocked = false;
+
+	for (const region of brain.regions) {
+		totalNeurons += region.neurons.length;
+
+		if (blocked) {
+			blockedRegions.push(region);
+			continue;
+		}
+
+		if (region.hasBomb) {
+			bombSource = region.name;
+			blockedRegions.push(region);
+			blocked = true;
+			continue;
+		}
+
+		activeRegions.push(region);
+
+		for (const neuron of region.neurons) {
+			if (!neuron.isDormant) {
+				firedNeurons++;
+				totalCounter += neuron.counter;
+			}
+		}
+	}
+
+	return {
+		activeRegions,
+		blockedRegions,
+		bombSource,
+		firedNeurons,
+		totalNeurons,
+		totalCounter,
+	};
+}

package/lib/watch.js

@@ -0,0 +1,79 @@
+// hebbian — Watch Mode
+//
+// Watches the brain directory for filesystem changes and auto-recompiles
+// all tiers when changes are detected. Uses hash-based change detection
+// to avoid redundant writes.
+
+import { watch } from 'node:fs';
+import { scanBrain } from './scanner.js';
+import { runSubsumption } from './subsumption.js';
+import { writeAllTiers } from './emit.js';
+
+/**
+ * Start watching a brain directory for changes.
+ * Auto-recompiles tiers when neurons are added/modified/removed.
+ *
+ * @param {string} brainRoot - Absolute path to brain root
+ */
+export async function startWatch(brainRoot) {
+	let lastHash = '';
+	let debounceTimer = null;
+
+	/** Scan brain and recompile if state changed. */
+	function recompile() {
+		const brain = scanBrain(brainRoot);
+		const result = runSubsumption(brain);
+		const hash = computeHash(result);
+
+		if (hash === lastHash) return;
+		lastHash = hash;
+
+		writeAllTiers(brainRoot, result, brain);
+		const ts = new Date().toLocaleTimeString();
+		console.log(`[${ts}] \u{1F504} recompiled — ${result.firedNeurons} neurons, activation ${result.totalCounter}${result.bombSource ? ` \u{1F4A3} BOMB: ${result.bombSource}` : ''}`);
+	}
+
+	// Initial compilation
+	recompile();
+	console.log(`\u{1F440} watching: ${brainRoot}`);
+	console.log('   Press Ctrl+C to stop.\n');
+
+	// Watch for filesystem changes
+	try {
+		const watcher = watch(brainRoot, { recursive: true }, (eventType, filename) => {
+			if (!filename) return;
+			// Ignore _index.md and _rules.md (our own output)
+			if (filename.endsWith('_index.md') || filename.endsWith('_rules.md')) return;
+			// Ignore hidden/internal
+			if (filename.startsWith('.') || filename.includes('/_') || filename.includes('\\_')) return;
+
+			// Debounce: wait 200ms after last change before recompiling
+			if (debounceTimer) clearTimeout(debounceTimer);
+			debounceTimer = setTimeout(recompile, 200);
+		});
+
+		// Keep process alive
+		await new Promise((resolve) => {
+			process.on('SIGINT', () => {
+				watcher.close();
+				console.log('\n\u{1F44B} watch stopped.');
+				resolve(undefined);
+			});
+		});
+	} catch (err) {
+		if (err.code === 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM') {
+			console.error('Recursive fs.watch not supported on this platform. Use Node.js >= 22.');
+		} else {
+			throw err;
+		}
+	}
+}
+
+/**
+ * Compute a simple hash from the subsumption result for change detection.
+ * @param {import('./subsumption.js').SubsumptionResult} result
+ * @returns {string}
+ */
+function computeHash(result) {
+	return `${result.firedNeurons}:${result.totalCounter}:${result.bombSource}:${result.activeRegions.length}`;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "hebbian",
+  "version": "0.1.0",
+  "description": "Folder-as-neuron brain for any AI agent. mkdir replaces system prompts.",
+  "type": "module",
+  "bin": {
+    "hebbian": "./bin/hebbian.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "test:coverage": "node --test --experimental-test-coverage",
+    "lint": "biome check .",
+    "lint:fix": "biome check --fix ."
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "brain",
+    "neuron",
+    "filesystem",
+    "memory",
+    "prompt",
+    "rules",
+    "cli",
+    "hebbian",
+    "subsumption"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IISweetHeartII/hebbian"
+  },
+  "homepage": "https://github.com/IISweetHeartII/hebbian#readme"
+}