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.

  ┌─────────────┐        ┌──────────────┐
  │  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.