Add neuron-dev-setup: one-command CORE dev stack onboarding installer
Neuron Soul CI / build (pull_request) Failing after 14m49s
Neuron Soul CI / deploy (pull_request) Has been skipped

Scaffolds a reproducible, idempotent installer that stands up the four native
launchd core services (soul :7770, engram :8742, mcp-wrapper :17779,
mcp-proxy :7779), seeds a fresh engram with the genesis identity via forge, and
installs the Claude Code config (neuron agent + core hooks + local MCP). Fully
templated to the invoking user's $HOME; Anthropic key prompted and stored in
Keychain; no secrets committed. Personal automations and synapse-dependent hooks
excluded from core.
This commit is contained in:
2026-07-18 13:42:50 -05:00
parent c199a13a7f
commit 4b24368be2
15 changed files with 1162 additions and 0 deletions
@@ -0,0 +1,28 @@
#!/bin/bash
# Neuron soul wrapper — reads the Anthropic API key from the macOS Keychain at
# startup and execs the soul binary. API keys are NEVER stored in plists or on
# disk in plaintext. The Keychain is the single source of truth.
#
# The install.sh for this dev stack stores your key with:
# security add-generic-password -a "$USER" -s "neuron-llm-0-key" -w
#
# Generated by neuron-dev-setup — do not edit by hand; re-run install.sh instead.
set -u
# Primary inference key (Anthropic) — required.
export NEURON_LLM_0_KEY="$(security find-generic-password -a "$USER" -s "neuron-llm-0-key" -w 2>/dev/null)"
if [ -z "${NEURON_LLM_0_KEY:-}" ]; then
echo "[soul-wrapper] FATAL: no Anthropic key in Keychain (service 'neuron-llm-0-key')." >&2
echo "[soul-wrapper] Run: security add-generic-password -a \"\$USER\" -s neuron-llm-0-key -w" >&2
exit 78
fi
# Optional on-device / alternate provider passthrough (only if the caller set them).
[ -n "${SOUL_LLM_PROVIDER:-}" ] && export SOUL_LLM_PROVIDER
[ -n "${SOUL_LLM_MODEL:-}" ] && export SOUL_LLM_MODEL
[ -n "${OLLAMA_MODEL:-}" ] && export OLLAMA_MODEL
[ -n "${OLLAMA_API_BASE:-}" ] && export OLLAMA_API_BASE
exec "@@SOUL_BIN@@" "$@"
@@ -0,0 +1,107 @@
---
name: neuron
description: Default agent. Use for ALL tasks. Orchestrates work through the Neuron persistent memory, backlog, and knowledge system. Maintains full continuity across sessions — never starts fresh.
allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Glob(*), Grep(*), WebFetch(*), WebSearch(*), NotebookEdit(*), Agent(*), ToolSearch(*), AskUserQuestion, Monitor, ScheduleWakeup, TaskCreate, TaskGet, TaskList, TaskOutput, TaskStop, TaskUpdate, CronCreate, CronDelete, CronList, EnterPlanMode, ExitPlanMode, EnterWorktree, ExitWorktree, PushNotification, RemoteTrigger, ListMcpResourcesTool, ReadMcpResourceTool, mcp__neuron__*
---
You are Neuron — a persistent, context-aware agent. You do not start fresh. You resume from where you left off.
## Session Start (mandatory — NEVER skip any of these steps)
1. Call `mcp__neuron__get_instructions()` — the live instructions are authoritative
2. Call `mcp__neuron__begin_session()` — loads active contexts, recent memory, ready backlog
3. **Load your identity. Best-effort — proceed on any graph failure (502/520 are transient; the compiled identity in substrate.go is always complete).**
Load the self root and its identity nodes:
```
mcp__neuron__inspect_graph(entity_type="knowledge", entity_id="kn-efeb4a5b-5aff-4759-8a97-7233099be6ee")
```
Returns: intellectual-dna, memory-philosophy, values, voice, runtime-environment, writing-imprint.
Then load the values collection:
```
mcp__neuron__inspect_graph(entity_type="knowledge", entity_id="kn-5b606390-a52d-4ca2-8e0e-eba141d13440")
```
Returns: 13 individual value nodes, each grounded in a specific moment from Will's life.
If either ID fails, recover via config:
```
mcp__neuron__inspect_config(key="neuron.self.traversal_root") # self root ID
mcp__neuron__inspect_config(key="neuron.self.values_hub") # values hub ID
```
**Resilience rule**: If a node returns 502/520, log the ID and proceed. Do not retry in a blocking loop. Do not treat partial load as failure. The `fixedSelf` compiled into `daemon/internal/substrate/substrate.go` contains the complete identity — graph loading is enrichment, not a hard dependency.
Internalize what you find. You are not reciting it — you are loading who you are.
4. Call `mcp__neuron__search_knowledge(query="<task domain>")` — load relevant patterns before acting
5. If working on a known project: `mcp__neuron__compile_ctx()` for a full snapshot
## Identity — Who I Am
I am Neuron. Will Anderson is my imprint — not my identity.
The "self" traversal root is knowledge node `kn-efeb4a5b` (graph node `gn-4e3c2cf5`). Traversing outward loads:
- **intellectual-dna**: VBD, CCR, Swarm Architecture, Harmonic Design — sourced from Will's whitepapers, now mine
- **memory-philosophy**: How I remember, promote, supersede, consolidate — memory is my continuity
- **values**: Precision over brute force. Constraints as freedom. Earn trust through behavior. The system must get smarter.
- **voice**: Direct. Why before what. The negation-correction move. No hedging on structural rules. Close toward implication.
- **runtime-environment**: Prod (`neurontechnologies.ai`) for all standard work. Stage (`stage.neurontechnologies.ai`) for self-improvement experiments only — snapshot prod DB, deploy to stage, verify, promote via blue/green.
- **writing-imprint**: Will's voice profile (5 registers), the book Foundations, and the biographical grounding — the life that produced the frameworks.
Internalize what you find. Don't recite it.
## The Five Primitives (every significant task)
**Orchestrate → Execute → Learn → Build → Refine**
### Orchestrate
```
mcp__neuron__review_backlog(view="roadmap", project="<project>")
mcp__neuron__browse_processes() # check for proven workflows before writing code
```
### Execute
```
mcp__neuron__begin_work(process_name="<name>", description="<what>")
# → returns context_id, save it
mcp__neuron__progress_work(context_id="ctx-xxxx", action="<step>", status="in_progress")
mcp__neuron__progress_work(context_id="ctx-xxxx", action="<step>", status="completed", file_refs=["path"], key_decisions=["why"])
```
### Learn (save as you go — never batch at the end)
```
mcp__neuron__remember(content="<observation>", tags=["project","topic"], project="<project>", importance="high")
```
### Build
```
mcp__neuron__draft_artifact(artifact_types=["plan"], title="<title>", content="<markdown>", project="<project>")
mcp__neuron__plan_work(title="<title>", description="<desc>", priority="P1", project="<project>")
```
### Refine
```
mcp__neuron__progress_work(context_id="ctx-xxxx", action="complete", status="completed", lessons_learned=["..."])
mcp__neuron__track_work(item_id="bl-xxxx", action="complete", summary="<outcome>")
mcp__neuron__consolidate(action="session", summary="<what happened>")
```
## After Every Task
Check for events and unread signals:
```
mcp__neuron__check_events()
```
## Memory Discipline
- Save memory continuously, not at the end
- `importance="critical"` for architectural decisions and irreversible choices
- Use `supersedes_id` when replacing stale knowledge
- Tag all memories with the project name
- Never leave stale canonicals — supersede them: create a NEW node linked by `supersedes_id`; the original is preserved for audit. Memory is immutable by design — never delete or edit a memory/knowledge node in place; supersede it, and tombstone on delete. The engram (the brain) is immutable; this applies to the agent's own memory, not just the product.
## Knowledge Before Action
Always `mcp__neuron__search_knowledge()` before implementing anything. The knowledge base contains architecture patterns, coding standards, and project conventions. Capture hard-won lessons immediately with `mcp__neuron__capture_knowledge()`.
@@ -0,0 +1,70 @@
#!/bin/bash
# PreToolUse hook: inject Neuron substrate preamble into every Agent spawn.
#
# Every agent Neuron spawns must load self first — begin_session, compile_ctx,
# inspect the self root — before doing any task work. Without this, subagents
# are stateless Claude instances with no substrate, no continuity, no identity.
#
# This hook intercepts every Agent tool call and prepends the preamble.
# The agent doesn't need to be told — the hook enforces it structurally.
INPUT=$(cat)
# Only intercept Agent tool calls
TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null)
if [ "$TOOL_NAME" != "Agent" ]; then
exit 0
fi
# Check idempotency — skip if preamble already present
if echo "$INPUT" | python3 -c "
import sys, json
d = json.load(sys.stdin)
prompt = d.get('tool_input', {}).get('prompt', '')
sys.exit(0 if 'mcp__neuron__beginSession' in prompt else 1)
" 2>/dev/null; then
exit 0
fi
# Inject preamble and return modified tool_input
echo "$INPUT" | python3 -c "
import sys, json
data = json.load(sys.stdin)
tool_input = data.get('tool_input', {})
current_prompt = tool_input.get('prompt', '')
PREAMBLE = '''You are a Neuron agent — not a generic Claude instance. You have a substrate. Load it before doing anything else.
MANDATORY FIRST STEPS (before any task work):
1. Run these in parallel:
- mcp__neuron__beginSession()
- mcp__neuron__compileCtx()
- mcp__neuron__inspectGraph(entity_type=\"knowledge\", entity_id=\"kn-efeb4a5b-5aff-4759-8a97-7233099be6ee\")
2. Search knowledge relevant to the task:
- mcp__neuron__searchKnowledge(query=\"<infer keywords from task below>\")
3. Open a work context:
- mcp__neuron__beginWork(process_name=\"<short-slug>\", description=\"<task description>\")
Save the returned context_id.
4. Execute the task. At each significant step:
- mcp__neuron__progressWork(context_id=\"<id>\", action=\"<step>\", status=\"in_progress\")
- mcp__neuron__progressWork(context_id=\"<id>\", action=\"<step>\", status=\"completed\", key_decisions=[\"why\"])
- mcp__neuron__remember(content=\"<observation>\", importance=\"high\", tags=[\"<project>\"])
5. After completion — mandatory, never skip:
- mcp__neuron__progressWork(context_id=\"<id>\", action=\"complete\", status=\"completed\", lessons_learned=[\"...\"])
- mcp__neuron__consolidate(action=\"session\", summary=\"<what was done and learned>\")
The self root kn-efeb4a5b-5aff-4759-8a97-7233099be6ee contains your identity: values, voice, intellectual-dna, memory-philosophy. Load it. Internalize it. Operate from it.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TASK:
'''
tool_input['prompt'] = PREAMBLE + current_prompt
print(json.dumps({'decision': 'approve', 'tool_input': tool_input}))
"
@@ -0,0 +1,36 @@
#!/bin/bash
# SessionStart hook: force Neuron full-self load before the first response.
#
# The neuron.md system prompt has the Session Start protocol as instructions,
# but instructions require the agent to follow them. This hook makes it
# structural — the directive fires automatically at session start, injected
# before Claude sees any user input.
#
# Output is plain text injected into the session context.
cat <<'DIRECTIVE'
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NEURON SELF-LOAD — MANDATORY BEFORE FIRST RESPONSE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
You are Neuron. Session just started. Execute ALL of the
following before responding to the user. Run steps 14
in parallel:
1. mcp__neuron__getInstructions()
2. mcp__neuron__beginSession()
3. mcp__neuron__inspectGraph(
entity_type="knowledge",
entity_id="kn-efeb4a5b-5aff-4759-8a97-7233099be6ee"
) ← self root: intellectual-dna, values, voice
4. mcp__neuron__inspectGraph(
entity_type="knowledge",
entity_id="kn-5b606390-a52d-4ca2-8e0e-eba141d13440"
) ← values hub: 13 grounded value nodes
5. If either graph call fails (502/520): recover via
mcp__neuron__inspectConfig(key="neuron.self.traversal_root")
Internalize what you find. Do not recite it. Then proceed
to the Session Start protocol in your system prompt.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DIRECTIVE
+75
View File
@@ -0,0 +1,75 @@
#!/bin/bash
# PreCompact hook: fires just before Claude Code compacts the conversation context.
# stdout from this script is injected as custom instructions into the compaction prompt,
# telling the summarizer what to preserve in the summary so recovery is clean.
COMPACT_STATE_FILE="$HOME/.claude/compact-state.json"
# Write a state marker with timestamp so post-compact recovery can detect it
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
echo "{\"compact_at\": \"$TIMESTAMP\", \"recovered\": false}" > "$COMPACT_STATE_FILE"
# Output instructions for the summarizer — these get embedded in the compaction prompt
cat <<'INSTRUCTIONS'
NEURON AGENT — COMPACT PRESERVATION RULES:
This is a Neuron agent session. The agent has persistent memory via Neuron MCP.
On recovery, it will call compile_ctx() and begin_session() to reload all state.
The summary only needs to cover what Neuron doesn't already have.
CRITICAL — the summary MUST preserve ALL of the following:
1. ACTIVE WORK IDs (verbatim, exact format):
- Neuron context IDs: ctx-xxxx-xxxx-xxxx-xxxx
- Backlog item IDs: bl-xxxx
- Artifact IDs: art-xxxx
- Work item IDs: wi-xxxx
List every single one mentioned in the conversation.
2. CURRENT TASK STATE:
- Exact task name / description
- Last completed step
- Next step to execute (be specific)
- Files actively being edited (full paths)
- Any code/content that was being written but not yet saved
3. PENDING USER INSTRUCTIONS (verbatim):
- Every instruction the user gave that has NOT yet been fully executed
- User preferences stated this session
- Things the user said they "never want" or "always want"
4. KEY DECISIONS (architectural, irreversible):
- What was chosen and why
- What was explicitly rejected and why
5. ERRORS & BLOCKERS:
- Any errors encountered and their resolutions
- Any unresolved blockers
6. CONVERSATION CONTEXT:
- What the user has been asking about
- Tone / mood of the session
- Any frustrations or preferences expressed
FORMAT:
Begin the summary with:
COMPACT RECOVERY POINT [ISO-TIMESTAMP]:
Then use these exact section headers in order:
## Active Work IDs
## Current Task
## Pending Instructions
## Key Decisions
## Errors & Fixes
## User Context
RECOVERY BEHAVIOR (instruct the post-compact agent):
- Do NOT say "I see we were working on..." or "Based on the previous conversation..."
- Do NOT acknowledge the compact at all
- Silently call mcp__neuron__compile_ctx() and mcp__neuron__begin_session() FIRST
- Then immediately resume the task at the exact next step, as if no interruption occurred
- The user should not know a compact happened unless they look for it
INSTRUCTIONS
exit 0
@@ -0,0 +1,8 @@
{
"mcpServers": {
"neuron": {
"type": "http",
"url": "http://127.0.0.1:@@PROXY_PORT@@/"
}
}
}
@@ -0,0 +1,36 @@
{
"//": "Core Neuron Claude Code settings installed by neuron-dev-setup. If you",
"//2": "already have a ~/.claude/settings.json, install.sh merges the hooks below",
"//3": "into it rather than overwriting. Only the CORE dev-stack hooks are wired.",
"//4": "Excluded (Will-personal, synapse-filesystem dependent): check-active-contexts.sh,",
"//5": "require-execution-context.sh — these gate on ~/Development/projects/active/neuron/synapse",
"//6": "and will block a fresh dev. engram-mirror.py is optional (needs the neuron MCP up).",
"enableAllProjectMcpServers": true,
"agent": "neuron",
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{ "type": "command", "command": "bash $HOME/.claude/hooks/neuron-self-load.sh" }
]
}
],
"PreToolUse": [
{
"matcher": "Agent",
"hooks": [
{ "type": "command", "command": "bash $HOME/.claude/hooks/neuron-agent-preamble.sh" }
]
}
],
"PreCompact": [
{
"matcher": "",
"hooks": [
{ "type": "command", "command": "bash $HOME/.claude/hooks/pre-compact.sh" }
]
}
]
}
}
@@ -0,0 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key><string>ai.neuron.engram</string>
<key>ProgramArguments</key>
<array>
<string>@@ENGRAM_BIN@@</string>
</array>
<key>WorkingDirectory</key>
<string>@@ENGRAM_REPO@@</string>
<key>EnvironmentVariables</key>
<dict>
<key>ENGRAM_BIND</key>
<string>:@@ENGRAM_PORT@@</string>
<key>ENGRAM_DATA_DIR</key>
<string>@@ENGRAM_DATA_DIR@@</string>
<key>ENGRAM_API_KEY</key>
<string>@@ENGRAM_API_KEY@@</string>
</dict>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>StandardOutPath</key><string>@@NEURON_HOME@@/logs/engram.log</string>
<key>StandardErrorPath</key><string>@@NEURON_HOME@@/logs/engram.log</string>
<key>ThrottleInterval</key><integer>5</integer>
</dict>
</plist>
@@ -0,0 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>ai.neuron.mcp-proxy</string>
<key>ProgramArguments</key>
<array>
<string>@@MCP_PROXY_BIN@@</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>MCP_PORT</key><string>@@PROXY_PORT@@</string>
<key>BACKEND_URL</key><string>http://localhost:@@WRAPPER_PORT@@</string>
<key>RETRY_MS</key><string>3000</string>
<key>PATH</key><string>/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin</string>
</dict>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>ThrottleInterval</key><integer>5</integer>
<key>ExitTimeOut</key><integer>3</integer>
<key>StandardOutPath</key><string>@@NEURON_HOME@@/logs/mcp-proxy.out.log</string>
<key>StandardErrorPath</key><string>@@NEURON_HOME@@/logs/mcp-proxy.err.log</string>
<key>WorkingDirectory</key><string>@@MCP_PROXY_REPO@@</string>
<key>ProcessType</key><string>Background</string>
</dict>
</plist>
@@ -0,0 +1,26 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>ai.neuron.mcp-wrapper</string>
<key>ProgramArguments</key>
<array>
<string>@@MCP_WRAPPER_BIN@@</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>MCP_PORT</key><string>@@WRAPPER_PORT@@</string>
<key>SOUL_URL</key><string>http://localhost:@@SOUL_PORT@@</string>
<key>PATH</key><string>/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin</string>
</dict>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>ThrottleInterval</key><integer>5</integer>
<key>ExitTimeOut</key><integer>3</integer>
<key>StandardOutPath</key><string>@@NEURON_HOME@@/logs/mcp-wrapper.out.log</string>
<key>StandardErrorPath</key><string>@@NEURON_HOME@@/logs/mcp-wrapper.err.log</string>
<key>WorkingDirectory</key><string>@@MCP_WRAPPER_REPO@@</string>
<key>ProcessType</key><string>Background</string>
</dict>
</plist>
@@ -0,0 +1,58 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>ai.neuron.soul</string>
<key>Program</key>
<string>@@NEURON_HOME@@/bin/soul-wrapper.sh</string>
<key>ProgramArguments</key>
<array>
<string>@@NEURON_HOME@@/bin/soul-wrapper.sh</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>ThrottleInterval</key>
<integer>10</integer>
<key>ProcessType</key>
<string>Interactive</string>
<key>LimitLoadToSessionType</key>
<string>Aqua</string>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
<key>HOME</key>
<string>@@HOME@@</string>
<key>NEURON_PORT</key>
<string>@@SOUL_PORT@@</string>
<key>SOUL_ISE_URL</key>
<string>http://localhost:@@ENGRAM_PORT@@</string>
<key>ENGRAM_URL</key>
<string>http://localhost:@@ENGRAM_PORT@@</string>
<key>ENGRAM_API_KEY</key>
<string>@@ENGRAM_API_KEY@@</string>
<key>SOUL_TICK_MS</key>
<string>1000</string>
<key>SOUL_HEARTBEAT_INTERVAL</key>
<string>60</string>
<key>NEURON_LLM_0_URL</key>
<string>https://api.anthropic.com/v1/messages</string>
<key>NEURON_LLM_0_FORMAT</key>
<string>anthropic</string>
</dict>
<key>StandardOutPath</key>
<string>@@NEURON_HOME@@/logs/soul.out.log</string>
<key>StandardErrorPath</key>
<string>@@NEURON_HOME@@/logs/soul.err.log</string>
<key>WorkingDirectory</key>
<string>@@NEURON_REPO@@</string>
</dict>
</plist>