neuron/neuron-dev-setup/README.md

neuron-dev-setup — one-command Neuron CORE dev stack

Stand up an identical Neuron brain + agent on a fresh Mac so any developer gets the same local runtime to build against. This is the CORE dev stack only — the four native launchd services that make Neuron think, remember, and speak MCP to Claude Code. Will's personal automations (catalyst, telegram, vessels, studio, self-review, world-integrator, council, compressor, snapshots, act-runner, …) are deliberately excluded.

⚠ Six of those "personal automations" are one missing subsystem — 2026-08-16

Authority: foundation/el/lang/spec/correspondence-and-censorship.md §7 (branch design/correspondence-and-censorship), transcribed with the full measured inventory in docs/architecture/06-cognitive-architecture.md §12.4.

The exclusion above and the fuller list further down are correct as a packaging decision — a fresh dev does not want Will's laptop's automations. But they are also a census of a fragmentation, and it should not be read as a list of unrelated conveniences. Consolidation had no owner, so it was implemented at every site that needed a piece of it. Every name in the set is a consolidation verb — compress, cultivate, digest, integrate, review, reify, beat.

Measured 2026-08-16 from ~/Library/LaunchAgents:

agent	what it runs	when	language	is it consolidation?
ai.neuron.compressor	council/compressor_service.py --port 7772	KeepAlive, resident	Python, outside el	yes
ai.neuron.council	council/council_service.py --port 7771	KeepAlive, resident	Python, outside el	yes (and a write-refusal — see council/README.md)
ai.neuron.cultivation-digest	tools/cultivation-digest.sh	23:55	shell	yes
ai.neuron.world-integrator	products/world-ingestor/integrator/run.py	06:00	Python, outside el	yes
ai.neuron.self-review	~/.neuron/bin/self-review-launch.sh	08:30	shell → CLI	yes
ai.neuron.engram-tick	pokes POST /api/tick via ~/.neuron/bin/engram-tick.sh	StartInterval = 600	shell	yes
ai.neuron.engram-backup	~/.neuron/bin/engram-backup.sh	StartInterval = 3600	shell	no — ops/backup
ai.neuron.snapshot-backup	~/.neuron/bin/snapshot-backup.sh	StartInterval = 900	shell	no — ops/backup
ai.neuron.act-runner-watchdog	act-runner-watchdog.sh	StartInterval = 120	shell	no — ops/CI

The last three times — 23:55, 06:00, 08:30 — are a sleep cycle implemented as launchd StartCalendarInterval entries. Someone understood it was consolidation and expressed it as three unrelated scheduled scripts in three languages, none aware of each other. Three of the six run in Python, outside el, so part of Neuron's consolidation does not run on his own substrate and cannot touch the geometry at all.

Consolidation is ambient, not scheduled. A brain has no cron job. (Precisely: it is not cron either — crontab -l has zero neuron entries. Every neuron schedule here is launchd.) The presence of a ticker is the diagnostic: every StartInterval, every Hour/Minute, every POST-to-beat marks a place where an intrinsic rhythm was replaced by an external clock. The one fragment with the correct shape is soul.el:731's continuous in-process awareness_run() loop, which is inside the core stack this repo does install — and it is the shape the six above fold into.

Nothing here changes what this repo installs. The core stack stays four services. The note exists so the exclusion list is not mistaken for a statement that these six are optional extras rather than one subsystem that never got built.

  ┌─────────────┐        ┌──────────────┐
  │  soul :7770 │ ─────► │ engram :8742 │     the mind ──► its memory substrate
  └─────────────┘        └──────────────┘
        ▲
        │
  ┌───────────────────┐
  │ mcp-wrapper :17779│  ─── MCP surface over the soul HTTP API (internal)
  └───────────────────┘
        ▲
        │
  ┌────────────────┐
  │ mcp-proxy :7779│  ◄─── Claude Code connects here (stable front door)
  └────────────────┘

Claude Code's neuron MCP server points at http://127.0.0.1:7779/ — the proxy. The proxy forwards to the wrapper (:17779), which calls the soul (:7770), which reads/writes the engram (:8742). The engram is the persistent brain.

Quick start

git clone <this-repo> && cd neuron-dev-setup
cp config.env.example config.env      # optional — edit ports/paths if you like
./install.sh                          # prompts for your Anthropic API key

Then verify:

curl http://localhost:8742/health     # engram
curl http://localhost:7770/health         # soul
curl http://localhost:7779/health         # mcp-proxy (what Claude Code uses)
launchctl list | grep ai.neuron

Open Claude Code — the neuron MCP tools should be live, backed by your own local brain. ./install.sh --dry-run shows every action without touching anything.

What the installer does (8 phases)

Phase	Action
1	Preflight: macOS/arm64, ensure git cc curl python3 + openssl@3 (via Homebrew)
2	Prompt for the Anthropic API key, store it in the macOS Keychain (never a file)
3	Clone neuron, engram, foundation; fetch the El toolchain; build 4 binaries + forge
4	Lay down ~/.neuron/{bin,logs,engram} and the templated soul-wrapper.sh
5	Generate + load the 4 core LaunchAgents (engram → soul → wrapper → proxy)
6	Seed a fresh engram with the genesis identity via forge install
7	Install Claude config: neuron agent, core hooks, local MCP registration
8	Health-check all four ports

Everything is idempotent (safe to re-run) and templated to the invoking user's $HOME — no path is hardcoded to another machine.

Prerequisites

• macOS on Apple Silicon (uses launchd; soul build flags assume arm64).
• Xcode Command Line Tools (xcode-select --install) — provides cc, git.
• Homebrew — for openssl@3, curl.
• An Anthropic API key — the soul's inference provider. Prompted for; stored in Keychain under service neuron-llm-0-key; read at launch by soul-wrapper.sh.
• Git access to Gitea (git.neuralplatform.ai) for the source repos.
• GCP access to project neuron-785695 Artifact Registry (default El toolchain source). Ask Will to grant it, or set EL_TOOLCHAIN_SOURCE=local.

Core-stack map (what gets replicated)

Service	Port	Binary	Built from	LaunchAgent
soul	7770	neuron/dist/neuron	dist/soul.c + El runtime, cc (CI recipe)	ai.neuron.soul
engram	8742	engram/dist/engram	engram repo src/server.el via elc→cc	ai.neuron.engram
mcp-wrapper	17779	neuron/mcp-wrapper/dist/neuron-mcp-wrapper	mcp-wrapper/src/main.el	ai.neuron.mcp-wrapper
mcp-proxy	7779	neuron/mcp-proxy/dist/neuron-mcp-proxy	mcp-proxy/src/main.el	ai.neuron.mcp-proxy

~/.neuron layout the installer creates

~/.neuron/
  bin/soul-wrapper.sh     # reads Anthropic key from Keychain, execs the soul binary
  logs/                   # soul.*.log, engram.log, mcp-*.log
  engram/                 # ENGRAM_DATA_DIR — the persistent brain (snapshot.json + db)

Identity seed. foundation/forge/seeds/neuron-genesis-seed.json carries identity_nodes[] + edges[] with fixed knowledge-node IDs (e.g. kn-efeb4a5b-5aff-4759-8a97-7233099be6ee, the "self" traversal root). Those exact IDs are referenced by the SessionStart self-load hook and the neuron agent, so seeding must preserve IDs — forge install <seed> is the mechanism.

Claude config installed (~/.claude/)

• agents/neuron.md — the Neuron agent (identity, session protocol, five primitives).
• mcp.json — registers neuron → http://127.0.0.1:7779/.
• settings.json hooks (CORE subset only):
  • SessionStart → neuron-self-load.sh (loads identity from the seeded engram)
  • PreToolUse:Agent → neuron-agent-preamble.sh (subagents load substrate first)
  • PreCompact → pre-compact.sh (clean context recovery)

Deliberately EXCLUDED from core

• check-active-contexts.sh and require-execution-context.sh — these depend on a separate filesystem repo ~/Development/projects/active/neuron/synapse. require-execution-context.sh is a hard Edit/Write gate that would block a fresh dev from editing any file without that synapse repo. Not core; excluded.
• engram-mirror.py (PostToolUse) — optional; mirrors MCP writes to engram.
• All Will-personal LaunchAgents: catalyst-*, telegram-gateway, vessel.*, studio, self-review, world-integrator, council, compressor, cultivation-digest, snapshot-backup, engram-backup, act-runner, keymap, invest, and the disabled ai.neuron.api (:7771 is a personal Python perception helper — confirmed not core).

Secrets — how they're handled

• Anthropic key: prompted for; stored in Keychain; read at launch. Never in a plist, this repo, or a log.
• Engram local token (ENGRAM_API_KEY): a loopback-only dev token, not a cloud secret. Defaults to a generated ntn-dev-* value; override in config.env.
• No cloud tokens, Vault tokens, CF-Access secrets, or founder keys are copied. (Will's live start-daemon.sh/neuron-api-launch.sh contain such keys — this installer intentionally does not use those files.)

Uninstall

./uninstall.sh                # stop + remove the 4 LaunchAgents and added Claude hooks
./uninstall.sh --purge-data   # ALSO delete ~/.neuron/engram (destroys the brain)

OPEN QUESTIONS (need Will to confirm)

1. El toolchain acquisition. The default path fetches el-runtime-c/-h and el-elc from GCP Artifact Registry (mirrors neuron/.gitea/workflows/ci.yaml). A new dev needs GCP access to neuron-785695. Is that the intended path, or should the El SDK be published/vendored for onboarding?
2. elc invocation for engram/wrapper/proxy. The soul build (`cc dist/soul.c
   • el_runtime.c) is verified from CI. The .el → .c transpile step for engram, mcp-wrapper, and mcp-proxy is inferred (elc -o <out.c>). Confirm the exact flags / entrypoints (CI notes elb` OOMs on Linux; macOS builds differ).
3. forge install ID preservation. Confirm forge install writes the seed's fixed kn- IDs verbatim (the self-load hook hardcodes kn-efeb4a5b…). If it re-mints IDs, the hook + agent identity load would break on a fresh brain.
4. engram repo layout. The live engram binary is built from src/server.el (Gitea repo neuron-technologies/engram, cloned in CI). Confirm that repo is the canonical source for onboarding (the local foundation/el/engram copy has the same src/server.el).
5. Home for this bundle — see below.

Where this should live (recommendation)

Recommendation: a dedicated neuron-dev-setup (or neuron-onboarding) repo — NOT neuron-code. neuron-code already exists as a real product ("Neuron Code", a coding tool with nc-cli + vessels — local products/neuron-code has commits); repurposing it for onboarding would collide with a shipped product's identity.

This bundle was scaffolded as neuron-dev-setup/ on branch feat/neuron-dev-setup in the neuron repo (off origin/main) and opened as a PR for review, because the neuron repo already hosts the soul source, the verified CI build recipe, and the mcp-wrapper/proxy sources — the natural review surface. If you'd rather it be its own repo, move this directory into a fresh neuron-dev-setup repo verbatim; nothing here depends on living inside the neuron repo.