NeuronFS

<p align="center">
  <img src="https://img.shields.io/badge/Go-1.22+-00ADD8?style=flat-square&logo=go" />
  <img src="https://img.shields.io/badge/Infra-$0-brightgreen?style=flat-square" />
  <img src="https://img.shields.io/badge/Neurons-420-blue?style=flat-square" />
  <img src="https://img.shields.io/badge/Zero_Dependencies-black?style=flat-square" />
  <img src="https://img.shields.io/badge/MIT-green?style=flat-square" />
</p>

<p align="center">
  <img src="docs/dashboard.png" alt="NeuronFS Dashboard — 3D Brain Visualization" width="800" />
  <br/>
  <a href="https://dashboarddeploy-six.vercel.app/"><strong>🔥 Live 3D Dashboard Demo</strong></a>
</p>

<p align="center"><a href="README.ko.md">🇰🇷 한국어</a> · <a href="README.md">🇺🇸 English</a> · <a href="MANIFESTO.md">📜 Manifesto</a> · <a href="LIFECYCLE.md">🧬 Lifecycle</a></p>

> **⚠️ v4.2 (2026-03-31) — Auto-Evolution Pipeline Complete**
>
> **Completed:**
> - **Emit engine optimization:** Dual-path sync (local `.gemini/` + global `~/.gemini/`), strength prefix batch rendering, Kanji micro-opcode double-expression removal for massive token savings
> - **Auto-evolution:** `--neuronize` (Groq-powered correction log analysis → auto contra neuron generation) and `--polarize` (positive English neurons → negative/inhibitory auto-conversion)
> - **Maintenance:** Duplicate neuron (similar/EN-KR) auto-merge complete (420 neurons stabilized), full PII purge
>
> **In Progress:** OS auto-start registration (L0), PII git-hook scanner, empty folder quarantine
>
> **Breaking:** `brain_v4/` excluded from git — users must `neuronfs --init` to create their own brain.
>
> Full changelog: [LIFECYCLE.md](LIFECYCLE.md) · [LIFECYCLE_EN.md](LIFECYCLE_EN.md)

# 🧠 NeuronFS
### *A filesystem-native hierarchical rule memory & prompt compiler for AI agents.*

---

## TL;DR

**`mkdir` replaces system prompts.** Folders are neurons. Paths are sentences. Counter files are synaptic weights.

```bash
# Create a rule = create a folder
mkdir -p brain/brainstem/禁fallback
touch brain/brainstem/禁fallback/1.neuron

# Compile = auto-generate system prompts
neuronfs ./brain --emit cursor   # → .cursorrules
neuronfs ./brain --emit claude   # → CLAUDE.md
neuronfs ./brain --emit all      # → All AI formats at once
```

| Before | NeuronFS |
|--------|----------|
| 1000-line prompts, manually edited | `mkdir` one folder |
| Vector DB $70/mo | **$0** (folders = DB) |
| Switch AI → migration | `cp -r brain/` — 1 second |
| Rule violation → wishful thinking | `bomb.neuron` → **physical halt** |
| Rules managed by humans | Correction → auto neuron growth |

### Quickstart

**Option A — Full engine (Go required)**

```bash
git clone https://github.com/rhino-acoustic/NeuronFS.git
cd NeuronFS/runtime; go build -o ../neuronfs .

./neuronfs --init ./my_brain        # Create brain with 7 regions
./neuronfs ./my_brain --emit all    # Compile to .cursorrules / CLAUDE.md / GEMINI.md
./neuronfs ./my_brain --api         # Dashboard at localhost:9090
./neuronfs ./my_brain --watch       # Auto-recompile on changes
./neuronfs ./my_brain --fire cortex/frontend/禁console_log   # +1 counter
./neuronfs ./my_brain --grow cortex/backend/禁raw_SQL        # Create neuron
```

Go gives you: `--init`, `--emit`, `--watch`, `--fire`, `--grow`, `--decay`, `--api`, `--supervisor`, `--neuronize`, `--polarize`.

**Option B — Live injection only (No Go needed)**

```bash
# 1. Create a brain manually (just folders)
mkdir -p ~/NeuronFS/brain_v4/brainstem/禁fallback
echo. > ~/NeuronFS/brain_v4/brainstem/禁fallback/5.neuron

mkdir -p ~/NeuronFS/brain_v4/cortex/frontend/禁console_log
echo. > ~/NeuronFS/brain_v4/cortex/frontend/禁console_log/9.neuron

# 2. Set environment variables
export NEURONFS_BRAIN="$HOME/NeuronFS/brain_v4"
export NODE_OPTIONS="--require $HOME/NeuronFS/runtime/v4-hook.cjs"

# 3. Start your IDE — done
cursor .
```

No build step. The hook is a single `.cjs` file with zero dependencies.
Node.js is already included in every Electron-based IDE (VS Code, Cursor, Windsurf).

Daily driver since January 2026. MIT License.

---

## Contents

| | Section | Description |
|---|---|---|
| 💡 | [Core Structure](#core-structure) | Folder = Neuron, Path = Sentence, Counter = Weight |
| 🧬 | [Brain Regions](#brain-regions) | 7 regions, priority cascade, hormone system |
| ⚖️ | [Governance](#governance) | 3-Tier injection, bomb circuit breaker, harness |
| 🧬 | [Neuron Lifecycle](#neuron-lifecycle) | Birth → Reinforcement → Dormancy → Apoptosis |
| 🏗️ | [Architecture](#architecture) | Autonomous loop, CLI, MCP, multi-agent |
| 📊 | [Benchmarks](#benchmarks) | Performance, competitor comparison |
| ⚠️ | [Limitations](#limitations) | Honest assessment |
| ❓ | [FAQ](#faq) | Expected questions and answers |
| 📖 | [Story](#story) | Why this exists |

---

## Core Structure

> **Unix said "Everything is a file." We say: Everything is folders.**

| Concept | Biology | NeuronFS | OS Primitive |
|---------|---------|----------|-------------|
| Neuron | Cell body | Directory | `mkdir` |
| Rule | Firing pattern | Full path | Path string |
| Weight | Synaptic strength | Counter filename | `N.neuron` |
| Reward | Dopamine | Reward file | `dopamineN.neuron` |
| Kill | Apoptosis | `bomb.neuron` | `touch` |
| Sleep | Synaptic pruning | `*.dormant` | `mv` |
| Connection | Axon | `.axon` file | symlink |

### Path = Sentence

Paths are natural language commands. Depth equals specificity:

```
brain/cortex/NAS_file_transfer/                    → Category
brain/cortex/NAS_file_transfer/禁Copy-Item_UNC/     → Specific rule
brain/cortex/NAS_file_transfer/robocopy_large/       → Sub-context
```

### Hanja Micro-Opcodes

`禁` (1 char) = "NEVER_DO" (8 chars). 3-5x more meaning density in folder names:

| Hanja | Meaning | Example |
|-------|---------|---------|
| **禁** | Forbidden | `禁fallback` |
| **必** | Required | `必auto_reference_KI` |
| **推** | Recommended | `推robocopy_large_files` |
| **警** | Alert | `警DB_delete_confirm_required` |

### Self-Evolution

`.cursorrules` is a static file you edit manually. NeuronFS is different:

```
AI makes mistake → correction → corrections.jsonl → mkdir (auto neuron growth)
AI does well → praise → dopamine.neuron (reward signal)
Same mistake 3x → bomb.neuron (entire output halted)
30 days unused → *.dormant (auto sleep)

**🔥 v4.2 Auto-Evolution:**
1. **auto-neuronize**: Groq LLM analyzes correction logs and auto-generates inhibitory (Contra) rules that prevent the same mistakes from ever recurring.
2. **auto-polarize**: Detects positive-form `use_X` rules and auto-converts them to strong Kanji micro-opcode inhibitory forms (`禁X_dependency`).
     ↓
Automatically reflected in next session's system prompt
```

---

## Brain Regions

7 brain regions layered via Brooks' Subsumption Architecture. **Lower P always suppresses higher P.**

```
brainstem(P0) > limbic(P1) > hippocampus(P2) > sensors(P3) > cortex(P4) > ego(P5) > prefrontal(P6)
```

| Region | Priority | Role | Examples |
|--------|----------|------|----------|
| **brainstem** | P0 | Absolute laws | `禁fallback`, `禁SSOT_duplication` |
| **limbic** | P1 | Emotion filter, hormones | `dopamine_reward`, `adrenaline_emergency` |
| **hippocampus** | P2 | Memory, session restore | `error_patterns`, `KI_auto_reference` |
| **sensors** | P3 | Environment constraints | `NAS/禁Copy-Item`, `design/sandstone` |
| **cortex** | P4 | Knowledge, skills (largest) | `frontend/react/hooks`, `backend/supabase` |
| **ego** | P5 | Tone, personality | `concise_execution`, `korean_native` |
| **prefrontal** | P6 | Goals, projects | `current_sprint`, `long_term_direction` |

### Hormone System

- **Dopamine** (`dopamineN.neuron`): Praise → positive weight boost
- **Adrenaline** (`adrenaline.neuron`): "urgent" detected → lower P suppresses higher P
- **Bomb** (`bomb.neuron`): 3x repeated mistake → entire region output disabled (circuit breaker)

### Axons — Cross-Region Wiring

16 `.axon` files connect 7 regions into a layered network

[truncated…]