A filesystem-native governance layer for AI agents. Folders are rules, counters are activation, Git is the audit trail.
# Add to your Claude Code skills
git clone https://github.com/rhino-acoustic/NeuronFSLast scanned: 5/30/2026
{
"issues": [
{
"type": "clone-failed",
"message": "Could not clone repository",
"severity": "medium"
}
],
"status": "WARNING",
"scannedAt": "2026-05-30T16:14:57.919Z",
"npmAuditRan": false,
"pipAuditRan": false
}NeuronFS is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by rhino-acoustic. A filesystem-native governance layer for AI agents. Folders are rules, counters are activation, Git is the audit trail. It has 141 GitHub stars.
NeuronFS returned warnings in SkillsLLM's automated security scan. It has no critical vulnerabilities, but review the flagged issues in the Security Report section before adding it to your workflow.
Clone the repository with "git clone https://github.com/rhino-acoustic/NeuronFS" and add it to your Claude Code skills directory (see the Installation section above).
NeuronFS is primarily written in Go. It is open-source under rhino-acoustic on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh NeuronFS against similar tools.
No comments yet. Be the first to share your thoughts!
Requires a passing catalog security scan. Resolve the flagged issues and resubmit to enable featuring.
A filesystem-native governance layer for AI agents.
NeuronFS keeps AI rules, memory, routing, and verification evidence in a local folder graph. The graph can be compiled into static instruction files for AI tools, or queried live through MCP before an agent acts.
It does not claim that a language model will always obey. It makes the required rules inspectable, repeatable, testable, and recoverable outside the model.
NeuronFS is built on a small set of non-negotiable design principles.
| # | Axiom | Implication |
|---|---|---|
| 0 | AI is a transistor, not intelligence. | A language model is a powerful switching element. It does not understand intent, guarantee consistency, or carry state between sessions. The governance layer must live outside the transistor. |
| 1 | Brain ≠ Information ≠ Tool. | Brain (rules, behavior patterns) is portable. Information (codemap, systemmap, transcripts) is environment-generated. Tools (runtime, scripts) are environment-installed. Only the brain travels when you move to a new machine. |
| 2 | Structure is context. | A folder path already carries meaning — address, depth, priority, timestamp, activation count. You do not need to open a file to understand the rule. |
| 3 | Deterministic before probabilistic. | Path tokens → exact match → synonym candidate → review → promotion. Embeddings can supplement, but they are not the first dependency. |
| 4 | Delivery 100% ≠ Compliance 100%. | NeuronFS guarantees that rules are delivered deterministically. It measures compliance separately. It does not claim that a model will always obey. |
| 5 | Evidence before promotion. | A conclusion is incomplete if it cannot be traced backward to source, evidence hash, decision context, rollback path, and final pointer. |
| 6 | Corrections become physical state. | Feedback is not a chat message. It materializes into the brain as a rule.md update with activation weight increase and audit trail. |
| 7 | Cost of prevention < cost of correction. | Per-turn harness overhead is small. One prevented mistake saves 10× more tokens, time, and risk than the overhead costs. The real efficiency is not per-turn savings — it is avoiding irreversible errors that cascade into debugging loops. |
These axioms are declared in the Manifesto with original dates and git hashes.
Modern work moves between AI tools:
Claude for planning
Gemini or Antigravity for IDE work
Codex for code execution
Copilot, Cursor, or Windsurf for editing
Each tool has a different memory surface. A rule learned in one session can disappear in the next. Long prompts are hard to audit, and generated summaries are not reliable evidence.
NeuronFS moves the rule layer out of the model and into the filesystem.
brainstem/禁/hardcoding/
brainstem/必/evidence_before_completion/
cortex/推/small_reversible_patches/
hippocampus/episodes/default_behavior_brain/
Folders are readable by humans, traversable by programs, diffable by Git, and stable across model sessions.
The public repository is intentionally smaller than the private operating tree. It contains source, tests, docs, public examples, and validators. It does not publish raw transcripts, private brain data, generated project maps, runtime sidecar state, or token files.
| Public claim | Evidence surface |
|---|---|
| Clean public checkout can build the runtime | go build in the beta smoke validator |
| The demo brain can emit six AI-tool instruction targets | scripts/validators/public_core_beta_smoke.ps1 |
| Public files exclude private/raw operational surfaces | scripts/validators/public_core_boundary.ps1 |
| Feature docs map commands to entrypoints, tests, gaps, and quark contracts | docs/FEATURE_MANIFEST.json, docs/QUARKMAP.json, docs/FEATURES_AND_COMMANDS.md |
| Public feature claims resolve generated codemaps by the active checkout's project id | scripts/validators/quark_integrity_gate.ps1, --quark-audit --project <project_root> |
| Public docs separate plans, docs, implementation, and live promotion | docs/NEURONFS_AI_BRIEF.md, docs/proofs/public_surface_verification.md |
Latest public-core validation recorded in this branch:
public_core_boundary.ps1 PASS
quark_integrity_gate.ps1 PASS
go test -v -count=1 -timeout 10m -buildvcs=false ./... PASS
go vet ./runtime PASS
node --check dashboard_hud/app.js PASS
git diff --check PASS
GitHub PR checks must pass after branch push
That is a public-core release claim, not a claim that a private full brain or live IDE supervisor is certified.
Recent public-core restoration also brings these local NeuronFS capabilities into the GitHub branch:
| Capability | Why it matters | Public evidence |
|---|---|---|
| Semantic index and synonym candidates | Folder paths and rule text can produce review-only candidate synonyms without embeddings or automatic promotion. | runtime/synonym_auto_gen.go, TestAutoExpandSynonymIndexWritesCandidatesOnly |
| Codemap freshness | Generated maps carry source hash/freshness metadata so stale maps cannot support current code claims. | runtime/codemap_freshness.go, GeneratedArtifactHeader |
| Correction materialization | MCP correct() and inbox processing materialize correction text into existing rule.md files instead of leaving the truth only in JSONL. |
runtime/correction_materializer.go, TestHealthCheckReportsMaterializationGap |
| Antigravity CDP UTF-8 injection | CDP prompt injection uses base64 UTF-8 decoding in the renderer to avoid non-ASCII corruption. | runtime/cdp_monitor.go, TestBuildCDPTextInsertExpression_UsesASCIIBase64Payload |
| Quark integrity gate | Feature claims must connect to codemap leaves, executable quark contracts, tests, and Korean/English labels before dashboard or autopilot controls execute. | docs/QUARKMAP.json, runtime/quark_contract.go, TestQuarkIntegrityGateResolvesDynamicProjectID |
| Autopilot and Agent Mode | Autopilot starts OFF, uses a queue SSOT, separates explicit workspace identity from delivery room, requires quark gate plus queue-scoped vector harness before execution, and lets a parent model decompose work into quark-parallel agent lanes. | runtime/autopilot_control.go, runtime/autopilot_queue.go, runtime/workspace_identity.go, dashboard_hud/app.js, TestAutopilotQueueAPIIsSharedSSOT |
| Exact workspace history | Transcript reads fail closed when a workspace is missing or ambiguous; cross-workspace reads require explicit scope. | runtime/mcp_handler_history.go, TestReadWorkspaceHistoryRejectsAliasFallback |
| Bilingual fire history | Rule/state activation records reusable Korean and English behavior text plus sidecar fire history. | runtime/neuron_fire_history.go, TestNeuronFireHistoryIsBilingualAndReadable |
Important boundary: Codex rollout JSONL mirroring proves that Codex conversations can be stored and read by workspace. It does not by itself prove automatic background neuronization. The transcript categorizer must explicitly parse Codex JSONL before making that claim.
git clone https://github.com/rhino-acoustic/NeuronFS.git && cd NeuronFS/runtime && go build -o neuronfs.exe . && NEURONFS_PORTABLE_EMIT=1 NEURONFS_MOCK_HOME=../examples/.mock_home ./neuronfs.exe ../examples/default_behavior_brain --emit all
git clone https://github.com/rhino-acoustic/NeuronFS.git; Set-Location NeuronFS\runtime; go build -o neuronfs.exe .; $env:NEURONFS_PORTABLE_EMIT="1"; $env:NEURONFS_MOCK_HOME="..\examples\.mock_home"; .\neuronfs.exe ..\examples\default_behavior_brain --emit all
Expected demo outputs:
examples/AGENTS.md
examples/CLAUDE.md
examples/.cursorrules
examples/.windsurfrules
examples/.github/copilot-instructions.md
examples/.mock_home/.gemini/GEMINI.md
NEURONFS_PORTABLE_EMIT=1 keeps the demo portable. It prevents emitted files from embedding private absolute paths.
flowchart LR
A["Folder brain"] --> B["Scan rules"]
B --> C["Resolve priority"]
C --> D["Static emit"]
D --> E["AGENTS.md / CLAUDE.md / GEMINI.md / IDE rule files"]
B --> F["MCP query"]
F --> G["Pre-action rule check"]
G --> H["Evidence / receipt / rollback"]
NeuronFS has two delivery paths:
| Path | Purpose | Example |
|---|---|---|
| Static emit | Write instruction files that AI tools can read without MCP | --emit all |
| Live MCP | Let an AI query the current rule graph before acting | --mcp, status, read_neuron, turn_alignment |
The same public brain can target multiple tools:
| Tool | Public emit target | Profile |
|---|---|---|
| Codex | AGENTS.md |
full |
| Claude Code | CLAUDE.md |
lite |
| Antigravity / Gemini | .gemini/GEMINI.md |
lite |
| VS Code Copilot | .github/copilot-instructions.md |
full |
| Cursor | .cursorrules |
lite |
| Windsurf | .windsurfrules |
full |
path = rule address
depth = specificity
mtime = freshness signal
counter = activation signal
rule.md = optional human-readable body
An empty folder can still be meaningful state. A file body improves readability, but the path itself remains the address.
Public docs use three Hanja path markers as compact governance markers:
| Marker | Plain meaning | Runtime meaning |
|---|---|---|
禁 |
never |