NeuronFS

Folders are neurons. Rules become paths. AI governance becomes a filesystem.

NeuronFS does not make AI infallible. It makes AI behavior bounded, replayable, and auditable.

NeuronFS turns scattered AI rule files into one local, auditable brain that emits rules for Cursor, Claude, Gemini, and Copilot simultaneously.

AI broke "no console.log" 9 times. On the 10th, mkdir 禁console_log was created. On the 11th, AI asked: "What is vorq?" The violation disappeared in that observed workflow.

The Problem Nobody Talks About

2026 reality: quota limits force every developer to mix multiple AIs.

Morning: Claude (Opus quota exhausted) → Afternoon: Gemini → Evening: GPT
Claude learned "禁console.log" → Gemini doesn't know → Violation → Pain

.cursorrules is Cursor-only. CLAUDE.md is Claude-only. Switch AI, rules evaporate.

Even within a single session:

Me: "Read the codemap before modifying"
AI: "Sure!" (starts coding without reading)

Text instruction compliance: ~60%. That's not governance — that's hope.

Quick Proof

git clone https://github.com/rhino-acoustic/NeuronFS.git && cd NeuronFS/runtime
go build -o neuronfs . && ./neuronfs --emit all

[EMIT] ✅ Cursor → .cursorrules
[EMIT] ✅ Claude → CLAUDE.md
[EMIT] ✅ Gemini → ~/.gemini/GEMINI.md
[EMIT] ✅ Copilot → .github/copilot-instructions.md
✅ 4 targets. One brain. Every AI. ~20MB binary.

Real Proof — Folder Names Reveal Meaning

Open any NeuronFS-managed project. Don't open a single file:

my_project/
├── brainstem/禁/hardcoding/
├── brainstem/必/codemap_SSOT_check/
├── cortex/skills/Codex_CLI_SOP/
├── hippocampus/episodes/apr21_budget_change/
├── prefrontal/roadmap/PPTX_automation/

You already know: absolute rules (禁), mandatory procedures (必), active skills, recent decisions, and future plans. Without opening anything.

This is what Folder = Neuron means. Vector databases store embeddings you can't see. JSON stores data you must parse. Only folder trees reveal meaning at a glance to both humans and AI.

4 Design Principles

1. Structure Can Narrow the Gap

A cheaper model with a persistent rule structure can behave more consistently than a stronger model with no persistent rules. Structure is the equalizer.

2. Rules Are Installed, Not Requested

Method	Compliance	Why
"Please read the codemap"	~60%	AI may decide it already knows
`neuronfs --emit all` → instruction files	~95%+ (n=1)	Rendered into the instruction layer.

3. Behavior Is Data

Neurons aren't templates written before you start. They're born from your actual mistakes. mistake → mkdir 禁mistake → never again. Your footprints become the path.

4. Folders Are the Interface

mkdir = CREATE. ls = READ. rm = DELETE. mtime = updated_at. The OS is the database.

How It Works

Axiom: Folder = Neuron

path      = rule (natural language)
filename  = counter (5.neuron = fired 5 times)
prefix    = governance type (禁=NEVER, 必=ALWAYS, 推=WHEN)
depth     = specificity (1=general, 3=specific)
mkdir     = learning
rm        = forgetting
OS metadata = embedding (mtime, size, permissions)

vorq — Coined-Word Harness (~95%+, n=1)

Words absent from training data → AI must look them up. 4 coined runewords:

vorq — load cartridge (force codemap read)
zelk — sync (cross-reference state)
mirp — freshness check (verify staleness)
qorz — community search first

If any runeword leaks into training data, governance_consts.go swaps it in 10 seconds.

7-Layer Subsumption (P0 → P6)

brainstem(P0) > limbic(P1) > hippocampus(P2) > sensors(P3) > cortex(P4) > ego(P5) > prefrontal(P6)
     ↑ absolutes     ↑ emotion    ↑ memory      ↑ context    ↑ knowledge   ↑ personality  ↑ goals

P0 rules are rendered with higher governance priority than P4 dev rules. bomb.neuron stops an entire region from rendering.

3-Tier Governance

禁hardcoding       → 🔴 NEVER   (absolute, immune to decay/prune)
必go_vet            → 🟢 ALWAYS  (mandatory every response)
推community_search  → 🟡 WHEN coding → THEN search first

OOM protection (applyOOMProtection()): when token budget is exceeded, 推 rules shrink first. 禁 rules are preserved last.

One Brain, Every AI

neuronfs --emit all → .cursorrules + CLAUDE.md + GEMINI.md + copilot-instructions.md

Static emission via emit_bootstrap.go (133 lines) + emit_tiers.go (426 lines, tiered rendering). Dynamic access via MCP server (20+ real-time tools). Both paths coexist.

What NeuronFS Guarantees

NeuronFS does not guarantee error-free AI.

It guarantees deterministic delivery of rules and bounded operation context.

✅ Rule-file emission is deterministic: one brain renders into target instruction files
✅ Whether the model follows those rules is measured separately
✅ Jloot cartridges are versioned and integrity-checked (Merkle chain)
✅ Codemap narrows edits to known code regions (bounded partial edits)
✅ Build/test gates catch compile-time and static-check failures
✅ Rollback preserves recoverability
✅ Human approval remains the final semantic gate

Delivery 100% ≠ Compliance 100%. NeuronFS guarantees the delivery path and measures compliance separately.

NFS Ecosystem — Beyond Brain

NFS/                              ← SSOT ecosystem container
├── brain/                        ← Transplant unit (7 regions, 707+ neurons)
├── codemap/                      ← Code index (63 entries, Go AST auto-generated)
│   └── {filename}/{function}/1.neuron
├── systemmap/                    ← System architecture map (22 neurons)
│   ├── data/     (brain, codemap, transcripts)
│   ├── infra/    (globalProjectRoot, governance_consts, start.bat)
│   └── runtime/  (supervisor, mcp, emit, api, telegram, autopilot...)
├── transcripts/                  ← Conversation transcripts (cron auto-categorized)
├── inbox/                        ← Global inbox (agent messages)
├── jloot/                        ← Cartridge serialization (encrypted VFS)
└── tools/                        ← Execution tools

Codemap (codemap_gen.go): Go AST auto-parses all runtime/ files → generates NFS/codemap/{file}/{func}/1.neuron. AI reads these before modifying code. SSOT for code structure.

Systemmap (NFS/systemmap/): 22 neurons mapping the entire system architecture. Data layer / Infra layer / Runtime layer. AI reads these to understand module relationships.

Comparison (8 Items)

#		`.cursorrules`	Mem0/Letta	NeuronFS
1	Rule delivery	Text = may be skipped	Probabilistic	100% deterministic
2	Observed compliance	~60%	~60%	~95%+ (vorq, n=1)
3	Multi-AI	❌ Cursor only	API-dependent	✅ `--emit all`
4	Priority system	❌ flat text	❌	✅ 7-layer (P0→P6)
5	Kill switch	❌	❌	✅ `bomb.neuron`
6	Infra cost	Free	$50+/mo	$0 (local OS)
7	Runtime dependencies	IDE-locked	Python+Redis	Zero
8	OOM protection	❌	❌	✅ auto-shrink

Fair note: Mem0/Letta excel at conversation memory (L3). NeuronFS does rule governance (L1). They are complementary layers, not competitors.
L3: Agent Memory (Mem0, Letta)     — conversation memory
L2: IDE Rules (.cursorrules)       — static, IDE-locked
L1: AI Governance (NeuronFS) ◀──   — model-agnostic, self-evolving

Benchmarks

Benchmarks are self-reported and reproducible from source. Run go test -run TestBM_ to verify. See docs/benchmarks.md for raw output.

Test	Result
BM-1 Rule fidelity (AgentIF CSR)	PASS
BM-2 Scale profile	PASS
BM-3 Similarity accuracy	PASS
BM-4 Lifecycle roundtrip	PASS
BM-5 Adversarial QA (LOCOMO)	PASS
BM-6 Production latency	PASS
BM-7 Multi-hop planning	PASS

Honesty — Limits & Self-Attack

Limitations

Issue	Reality	Our Answer
Scale ceiling	1M folders: OS handles it, human cognition doesn't	L1 cache design — controls the neck, not the world
Ecosystem	Solo project	Open source + zero runtime deps = permanent buildability
vorq validation	n=1 observation	Principle is model-agnostic; more testing underway
Instruction drift	Creative models may reinterpret	vorq + 禁 prefix = strongest available mitigation
Original systems	60% existing tech, 40% novel	Honest classification. See wiki for breakdown

Self-Attack — 10 Rounds

Result: 7 defended · 3 limits acknowledged · 0 fatal

#	Attack	Verdict
1	vorq is n=1	⚠️ Needs validation — principle is model-agnostic
2	vorq gets learned → swap in 10 sec ($0)	✅ Defended
3	Rules files unread by AI? → coding agents auto-load	✅ Defended
4	P0 is still text → acknowledged fundamental limit	⚠️ Limit
5	mkdir vs vector → L1/L2 complementary, not competing	✅ Defended
6	Merkle = tampering only by external actors	✅ Defended
7	Lifecycle decay too aggressive? → 禁 immune	✅ Defended
8	LLM hallucination in evolve → dry_run + human approval	✅ Defended
9	Single-machine only → cartridge export (.jloot)	✅ Defended
10	No formal verification → bounded claims only	⚠️ Acknowledged

Showing weakness first builds trust. This is a research-paper approach, not a marketing approach.

Expandability

Domains: Lawyer brain, accountant brain, PM brain — same binary, different folders.

2-Track Architecture:

Big model (GPT-5.5/Claude) → decomposes tasks into quarks
Small model (Groq $0.05/1M) → executes quarks in parallel
Interface between tracks = neuron folders

Wargame Methodology: Both AI sides' blind spots → merged into neurons → prompts improve regardless of which AI runs next.

Autopilot: 5-minute idle → autonomous evolution via Gemini CLI. Transcript analysis → unresolved items → auto-fix. Human approval required.

Use Cases:

Scale	Example
Solo developer	Personal coding rules across Claude/Cursor/Gemini
Multi-agent swarm	bot1/enfp/architect with shared brain + inbox/outbox
Enterprise	Department brains with RBAC + Merkle audit trail

Universal Rules: 268 personal neurons → AI extraction (#ai-expanded) → 24 domain-agnostic SOPs. Your behavioral experience becomes transferable intelligence.

Getting Started

# Linux/macOS/PowerShell 7+
git clone https://github.com/rhino-acoustic/NeuronFS.git && cd NeuronFS/runtime && go build -o neuronfs . && ./neuronfs --emit all

# Windows PowerShell 5.1
git clone https://github.com/rhino-acoustic/NeuronFS.git; cd NeuronFS/runtime; go build -o neuronfs.exe .; .\neuronfs.exe --emit all

Advanced commands:

neuronfs <brain> --grow <path>     # Create neuron (60% similar = auto-merge)
neuronfs <brain> --fire <path>     # Activate neuron (+1 counter)
neuronfs <brain> --signal <path> dopamine  # Positive reinforcement
neuronfs <brain> --signal <path> bomb      # 3x repeated mistake → block
neuronfs <brain> --evolve          # AI evolution (dry run by default)
neuronfs <brain> --diag            # Brain tree visualization
neuronfs <brain> --api             # 3D dashboard (localhost:9090)

🎲 Chaos Engineering:

cd cmd/chaos_monkey && go run main.go --dir ../../my_brain --mode random --duration 10
# 10 seconds of random destruction → self-repair pipeline activates → 0 data loss

🏗️ Architecture (145 files, 24,595 lines)

Single Binary, 3 Modes (~20MB)

Mode	Entry	Lifetime	Communication
`--supervisor`	start.bat → `runSupervisor()`	Daemon (auto-restart)	HTTP :9090 + TCP :9091
`--mcp`	IDE settings.json → spawn	IDE session	stdio JSON-RPC
`--emit/grow/fire/...`	CLI one-shot	Immediate exit	stdout

707 Neurons, 7 Regions

Region	Priority	Count	Role
🛡️ brainstem	P0	70	Absolutes (禁/必)
💓 limbic	P1	7	Emotion filter (EmotionPrompt)
📝 hippocampus	P2	81	Memory/episodes
👁️ sensors	P3	3	Environment constraints
🧠 cortex	P4	521	Knowledge/skills (codemap included)
🎭 ego	P5	7	Personality/tone
🎯 prefrontal	P6	13	Goals/plans

Supervisor — 8-Step Hourly Cron

git → backup → prune → context → categorize → log → verify → dedup

MCP Server — 20+ Tools

Tool	Function
`grow`	Create neuron (60% similar = auto-merge)
`fire`	Activate (+1 counter, auto-create if missing)
`signal`	dopamine (reinforce) / bomb (block) / memory (log)
`correct`	PD correction → corrections log → personalized neurons
`search`	Keyword search + time filter + sort (activation/created_at)
`read_brain`	Full brain state as JSON
`read_neuron`	Single neuron rule content
`evolve`	Gemini CLI autonomous evolution (dry_run/apply)
`health_check`	Duplicates, empty folders, bomb status, merge suggestions
`report`	Layered queue: urgent/normal/low priority
`log_episode`	Permanent episode recording in hippocampus
`read_history`	Workspace conversation history
`delegate_task`	P2P task delegation (bot1/enfp/architect)
`dashboard_state`	Real-time API state for 3D dashboard
`write_message`	Direct inbox/outbox control

emit vs MCP: emit = static compilation (system prompt). MCP = dynamic access (real-time CRUD). Both coexist.

Brain Engine

brain.go (593 lines): Brain/Region/Neuron structs, scanBrain(), subsumption
neuron_crud.go (379 lines): grow/fire/rollback/signal
lifecycle.go (545 lines): birth → growth → decay → death (30-day dormancy)
hebbian.go (178 lines): Hebbian learning + sleepConsolidate()
axon_memory.go: Cross-region .axon references, HealAxonLinks() auto-repair
similarity_index.go: TF-IDF reverse index, Jaccard+Cosine, compound word splitting
immunity.go: Deletion protection for 禁 rules, validator.go for data integrity
memory_ltp.go + procedural_memory.go + skill_accumulator.go: Long-term memory + skill injection

Emit Pipeline

emit_bootstrap.go → emit_tiers.go (OOM protection) → emit_format_rules.go (646 lines)
emit_ki_sync.go: Knowledge Item sync
skill_accumulator.go: On-demand skill injection into system prompt

Automation

watch.go + brain_watcher.go: fsnotify → auto-reinject on brain changes
context_hijacker.go + cdp_client.go: Chrome DevTools Protocol context extraction
hijack_orchestrator.go: 5-min idle → autonomous evolution
agent_bridge.go + agent_message_queue.go: Multi-agent message routing
transcript.go (583 lines) + transcript_categorizer.go: Conversation transcript → auto-categorized neurons
summary_bot.go + news_publisher.go: Auto-summary + news publishing via Telegram
backlog.go: RunBacklogLoop() inbox auto-classification

Security & VFS

merkle_chain.go (206 lines): SHA-256 Merkle chain, BuildChain/VerifyChain/IncrementalUpdate
dek_manager.go (319 lines): Data Encryption Key lifecycle (create/rotate/destroy)
crypto_neuron.go: Per-neuron encryption/decryption via DEK
access_control.go (153 lines): RBAC, role-based neuron access
pii_masker.go (233 lines): Automatic PII masking (GDPR)
vfs_core.go + vfs_mount.go + vfs_ops.go: OverlayFS simulation, Copy-on-Write, RAM-only decryption
cartridge_crypto.go: XChaCha20 + Argon2id, .jloot files, zero disk trace

Diagnostics & Self-Repair

self_repair.go + self_repair_pipeline.go: Error detection → auto-recovery
error_engraver.go (204 lines): Repeated error engraving, 3x → bomb trigger
panic_ux.go (387 lines): RenderFlatlineOnPanic — crash UX
diag.go + diag_harness.go: Brain tree visualization + settings validation

LLM & External Integration

llm_groq.go (278 lines): Groq API, Llama 4 Maverick ($0.05/1M)
emotion_prompt.go: Functional emotion → prompt modulation (Microsoft 2023)
telegram_bridge.go (591 lines): PD↔AI real-time channel, message→MCP conversion
crawler.go: External data → auto-neuron creation
evolve_context.go: Gemini CLI integration, dry_run/apply
dream_cycle.go + spaced_repetition.go: Sleep consolidation + spaced repetition firing

Ports

Port	Service
9000	CDP (Antigravity IDE)
9090	REST API (supervisor → dashboard)
9091	TCP Singleton Lock
stdio	MCP JSON-RPC (IDE → --mcp)

145 Go source files. 24,595 lines. 427+ tests. Zero runtime dependencies.

💡 Deep Dive: Core Structure, Runewords, Limbic, Jloot, Extended Benchmarks

Core Structure — Biology Mapping

Every folder path is a natural-language sentence: brainstem/禁/hardcoding = "It is absolutely prohibited to hardcode values." The Hanja prefixes (禁/必/推) act as opcodes that AI cannot reinterpret.

16 Runewords (Diablo II Inspired)

Runeword	Function	Trigger
vorq	Load cartridge	Before any code modification
zelk	Sync state	After multi-file changes
mirp	Freshness check	Before referencing cached data
qorz	Community search	Before implementing new patterns
+12 more	See Wiki →

Limbic — EmotionPrompt (Microsoft 2023)

Functional emotions modulate prompts: anger → verification strength ↑, curiosity → exploration ↑. Not sentiment analysis — behavioral amplification.

Jloot — Encrypted VFS

graph LR
    A[Brain Folder] -->|package| B[.jloot Cartridge]
    B -->|XChaCha20 + Argon2id| C[Encrypted File]
    C -->|mount| D[RAM-only VFS]
    D -->|read| E[Decrypted Neurons]
    E -->|unmount| F[Zero Disk Trace]

QA Pipeline

Three-AI verification: Antigravity (primary) + GPT-5.5 via Codex CLI (cross-review) + Groq/Llama (execution). This is qualitative design feedback, not independent benchmark validation.

FAQ

Q: "How is this different from Notion?" A: Notion is a document. NeuronFS is a governance system. Permission separation (7-layer cascade), kill zones (bomb.neuron), and machine-readable priority (禁>必>推) don't exist in Notion.

Q: "1000+ neurons won't blow the token limit?" A: Triple defense: ① tiered on-demand rendering (emit_tiers.go) ② 30-day untouched → dormant (lifecycle.go) ③ --consolidate LLM merge.

Q: "Why hasn't big tech done this?" A: GPU is money. "Just throw PDFs at AI" is easier. mkdir feels primitive. That's exactly why nobody did it, and why it works.

Wiki — 4 Acts, 22 Episodes

Act	Theme
Act 1	Doubt & Discovery
Act 2	Trials & Wargames
Act 3	Proof & Benchmarks
Act 4	Declaration & Ultra-Plan

Changelog

Version	Highlights
v5.2	MCP 20+ tools, Codex CLI delegation, 3D dashboard
v5.1	Universal Axonization, vorq harness
v5.0	Jloot VFS, Merkle chain, PII masking
v4.4	7-layer subsumption, 3-Tier governance

NeuronFS does not make AI infallible. It makes AI behavior bounded, replayable, and auditable.

Created by 박정근 (PD) — rubisesJO777 145 Go files · 707+ neurons · 427+ tests · Self-healing immune system · Single binary · Zero runtime dependencies

Name		Name	Last commit message	Last commit date
Latest commit History 1,708 Commits
.gemini		.gemini
.github		.github
NFS		NFS
brain_v4		brain_v4
docs		docs
runtime		runtime
scratch		scratch
scripts		scripts
sensors/gateway		sensors/gateway
static		static
telegram-bridge/_archive		telegram-bridge/_archive
templates/advanced_coder_brain		templates/advanced_coder_brain
.editorconfig		.editorconfig
.geminiignore		.geminiignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.neuronfs_init		.neuronfs_init
LICENSE		LICENSE
MANIFESTO.md		MANIFESTO.md
README.ko.md		README.ko.md
README.md		README.md
go.mod		go.mod
go.sum		go.sum
start.bat		start.bat

Folders and files

Latest commit

History

Repository files navigation

NeuronFS

Folders are neurons. Rules become paths. AI governance becomes a filesystem.

The Problem Nobody Talks About

Quick Proof

Real Proof — Folder Names Reveal Meaning

4 Design Principles

1. Structure Can Narrow the Gap

2. Rules Are Installed, Not Requested

3. Behavior Is Data

4. Folders Are the Interface

How It Works

Axiom: Folder = Neuron

vorq — Coined-Word Harness (~95%+, n=1)

7-Layer Subsumption (P0 → P6)

3-Tier Governance

One Brain, Every AI

What NeuronFS Guarantees

NFS Ecosystem — Beyond Brain

Comparison (8 Items)

Benchmarks

Honesty — Limits & Self-Attack

Limitations

Self-Attack — 10 Rounds

Expandability

Getting Started

🏗️ Architecture (145 files, 24,595 lines)

Single Binary, 3 Modes (~20MB)

707 Neurons, 7 Regions

Supervisor — 8-Step Hourly Cron

MCP Server — 20+ Tools

Brain Engine

Emit Pipeline

Automation

Security & VFS

Diagnostics & Self-Repair

LLM & External Integration

Ports

💡 Deep Dive: Core Structure, Runewords, Limbic, Jloot, Extended Benchmarks

Core Structure — Biology Mapping

16 Runewords (Diablo II Inspired)

Limbic — EmotionPrompt (Microsoft 2023)

Jloot — Encrypted VFS

QA Pipeline

FAQ

Wiki — 4 Acts, 22 Episodes

Changelog

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages