will.anderson
5e15d90659
~226 lines of architecture documentation that were written, left uncommitted in the working tree, and nearly lost. None of it was on main. Recovered from a stash taken while merging tonight's fixes. Substantive content, not notes: - Peer import-of-understanding PROVEN by execution. A exported a skill-geometry; on the receiver `think` went "geometry unavailable" -> operable. Cosine 1.0 on both the raw-geometry and text/dharma-bus transports, bidirectional. The mind-not-paste evidence: n_support 27 on source vs 3 on receiver, i.e. the imported geometry wires into the host manifold rather than sitting inert. Honest boundary recorded too: proven between forks sharing one embedder, UNTESTED cross-embedder. - "Teacher" renamed GUIDE, and the distinction is load-bearing: its output is grounded/verified before trust. A teacher you believe; a guide you check. - Layers are named persistent relational neighborhoods, not storage tiers, with their own growth and threshold-lock policy (note->canonical maturation lifted from single nodes to a region). - The consciousness theories (Global Workspace, IIT's Phi, attention-schema, higher-order thought, active inference, interoception) read as geometric LENSES over one manifold rather than competing mechanisms. Functional problems fall out; the hard problem explicitly not claimed solved. - Growth is bounded/logistic, not geometric — exponential growth is the cancer shape. Two-rate discipline: explore fast in local geometry, grow the engram slowly by verifier-gated merge. - Orchestration as a geometric operation: critical path as geodesic, float as displacement, @manager compiles the work-graph. Single-writer enforced by capability (Rule 4). - The decorated seam, the API surface collapse to geometry ops, and the distributed-self thesis — each tiered honestly against what is actually proven vs staged vs unbuilt. Also gitignores dist-fresh/ (regenerate scratch dir, a build artifact). Not included from the same stash: awareness.elh and dist/elp-c-decls.h, which are generated artifacts now gitignored per #154/#158.
148 lines
9.3 KiB
Markdown
148 lines
9.3 KiB
Markdown
# Neuron — Architecture Overview
|
|
|
|
> Status: living document. Grounded in the committed source of the `neuron`
|
|
> repository as of 2026-08-10. Every structural claim cites a real file. Where a
|
|
> statement is inferred rather than read directly, it is labelled *(inference)*
|
|
> or *(unverified/TODO)*.
|
|
|
|
## What Neuron is
|
|
|
|
Neuron is a **persistent CGI (Cultivated General Intelligence) runtime**. It is
|
|
not a chatbot and not a stateless API in front of an LLM. It is a long-lived
|
|
process that *remembers* — it carries an identity, a graph of memory and
|
|
knowledge, and an autonomous idle-cognition loop across restarts. The LLM is one
|
|
resource it calls; the durable part is the **engram** (the graph) and the
|
|
**soul** (the program that reasons over it).
|
|
|
|
Three things run together to make that true:
|
|
|
|
- **The soul** — the compiled El program in this repo. It owns the HTTP surface,
|
|
the cognitive API, the request pipeline (`layered_cycle`), and the autonomous
|
|
awareness daemon. Entry point `soul.el`, served by `handle_request`
|
|
(`routes.el:358`).
|
|
- **The engram** — the graph store. Node/edge model, spreading activation, and
|
|
Hebbian co-activation physically live in the shared El runtime
|
|
(`el_runtime.c`); `engram/src/server.el` is a thin HTTP face on `:8742`. The
|
|
engram is a *sibling* repo (`foundation/el/engram`), compiled and co-located at
|
|
runtime, not part of this repo's source tree.
|
|
- **The El runtime** — `el_runtime.c` / `el_runtime.h`. Every compiled El binary
|
|
links it. It implements all builtins (`engram_`*, `http_*`, `json_*`, LLM,
|
|
crypto) and *is* the database — "no SQL, no db layer, no SQLite"
|
|
(`../foundation/el/engram/src/server.el:4-6`).
|
|
|
|
Neuron persists memory itself — this repo is the memory system. Do not confuse
|
|
it with the Neuron desktop/UI application, which is **out of scope** here and is
|
|
only ever a *client* of the MCP surface described in this set.
|
|
|
|
## System context
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────┐
|
|
│ MCP clients (Claude Code, Soma chat UI, agents) │
|
|
│ — talk MCP JSON-RPC over stdio, or HTTP to the soul │
|
|
└───────────────┬────────────────────────────────────────────┘
|
|
│ MCP JSON-RPC (stdio)
|
|
┌──────────▼──────────┐
|
|
│ mcp-proxy :7779 │ byte-forwarder + retry + health
|
|
└──────────┬──────────┘
|
|
│ MCP JSON-RPC (stdio→HTTP)
|
|
┌──────────▼──────────┐
|
|
│ mcp-wrapper :17779 │ JSON-RPC ⇄ soul REST; ~90-tool catalog
|
|
└──────────┬──────────┘
|
|
│ HTTP (REST)
|
|
┌──────────▼──────────┐ ┌──────────────────────────┐
|
|
│ soul :7770 │──HTTP──▶│ engram :8742 │
|
|
│ handle_request │ │ graph store (snapshot) │
|
|
│ layered_cycle │◀──────▶│ el_runtime.c = the DB │
|
|
│ awareness daemon │ └──────────────────────────┘
|
|
└──────────┬──────────┘
|
|
│ HTTP
|
|
┌───────────────┼───────────────┬───────────────┐
|
|
▼ ▼ ▼ ▼
|
|
Axon backend neuron-connectd LLM API (self-callback
|
|
:backlog/ :7771 connectors Anthropic NEURON_API_URL)
|
|
artifacts/ (MCP bridges) format
|
|
projects
|
|
```
|
|
|
|
*Ports/topology verified*: proxy `:7779` and wrapper `:17779`
|
|
(`mcp-proxy/src/main.el`, `mcp-wrapper/src/main.el`); soul `:7770`
|
|
(`NEURON_PORT`, k8s `deployment-blue.yaml`); engram `:8742` (`entrypoint.sh`,
|
|
`server.el:711`). The Axon backend, `neuron-connectd` (`:7771`), and the LLM are
|
|
external dependencies the soul reaches over HTTP (`routes.el` `axon_get/post`,
|
|
`connectd_get/post`).
|
|
|
|
## The two external interfaces
|
|
|
|
Neuron exposes exactly two surfaces, and it is worth being precise about the
|
|
difference because they drive the whole component split:
|
|
|
|
1. **The MCP surface** — the *tool* interface. MCP clients call tools
|
|
(`begin_session`, `remember`, `search_knowledge`, `inspect_graph`,
|
|
`cultivate`, …). This is the interface Claude Code and agents use. It is
|
|
delivered by the **proxy → wrapper** chain, which translates MCP JSON-RPC
|
|
into the soul's HTTP REST calls. The wrapper carries a catalog of ~90 tools
|
|
(`mcp-wrapper/src/main.el`).
|
|
2. **The HTTP API** — the *cognitive* interface. The soul serves REST on
|
|
`:7770`. `routes.el` dispatches; `neuron-api.el` handles the cognitive
|
|
endpoints (`/api/neuron/`*). This same surface backs the chat product
|
|
(`/api/chat`, `/api/sessions`) and the studio UI (`/`).
|
|
|
|
In production the MCP client connects to the soul's HTTP directly — the
|
|
`neuron-mcp` ClusterIP Service targets `:7770` (`service.yaml`) and the
|
|
proxy/wrapper chain is primarily the **local developer adapter** that lets a
|
|
stdio MCP client speak to an HTTP soul. See `04-runtime-and-deployment.md`.
|
|
|
|
## Component map (summary)
|
|
|
|
The full VBD classification is in `01-vbd-decomposition.md`. In one glance:
|
|
|
|
|
|
| Layer | Module(s) | Role |
|
|
| --------------------- | ------------------------------------------- | ------------------------------------------------------------------------ |
|
|
| HTTP dispatch | `routes.el` | Manager — hand-written method/path dispatch |
|
|
| Cognitive API | `neuron-api.el` | Managers + Engines — session/memory/knowledge/graph/cultivation handlers |
|
|
| Request pipeline | `soul.el` `layered_cycle` | Manager — L1 safety → L2 stewardship → L3 imprint |
|
|
| Boot + identity | `soul.el` | Manager — compose layers, seed identity graph, start server + daemon |
|
|
| Autonomous cognition | `awareness.el` | Manager (`awareness_run`) + Engines (curiosity, attend, threat) |
|
|
| Memory access | `memory.el` | Resource Accessor over the engram FFI/HTTP |
|
|
| Store | `engram/server.el` + `el_runtime.c` | Accessor (HTTP) over the real graph engine |
|
|
| Request-layer rules | `safety.el`, `stewardship.el`, `imprint.el` | Engines |
|
|
| Conversation sessions | `sessions.el` | Manager (chat product) |
|
|
| MCP transport | `mcp-proxy`, `mcp-wrapper` | Managers/Accessors — protocol boundary |
|
|
| Build | `manifest.el`, `dist/soul.c`, El toolchain | amalgamation → `soul.c` → binary |
|
|
|
|
|
|
## Reading guide
|
|
|
|
- `**01-vbd-decomposition.md`** — the volatility analysis. Start here for *why*
|
|
the boundaries fall where they do. Contains the full Manager/Engine/Accessor/
|
|
Utility table and the honest list of where the real code diverges from VBD.
|
|
- `**02-components.md*`* — per-subsystem detail: routing, the cognitive API, the
|
|
memory & activation engine, the MCP transport chain. Read after 01.
|
|
- `**03-data-and-memory.md**` — the engram graph model: node/edge structs,
|
|
layers, the two tier systems, write-protection, tombstone/supersede
|
|
immutability, persistence.
|
|
- `**04-runtime-and-deployment.md**` — process/port topology, the end-to-end MCP
|
|
request path, local vs GKE blue/green, secrets/config.
|
|
- `**05-el-and-build.md**` — the El language, the `elc`/`elb` toolchain, the
|
|
amalgamation → `soul.c` → binary pipeline, and the compile-time capability
|
|
gates.
|
|
|
|
## A note on honesty
|
|
|
|
Two facts shape everything below and are stated once here so the rest reads
|
|
straight:
|
|
|
|
1. **The most volatile logic — the activation and Hebbian math — lives in the
|
|
most stable-looking layer**, the C runtime (`el_runtime.c`). The El files in
|
|
this repo are largely a *Manager + Accessor shell* around that core. This
|
|
inverts the usual VBD expectation and is called out wherever it matters.
|
|
2. **The immutability guarantee lives above the store, not in it.** The engram
|
|
HTTP server will hard-delete a node (`DELETE /api/nodes/:id` →
|
|
`engram_forget`, `server.el:322`). Immutability holds only because the
|
|
neuron-api / MCP layer routes every user-facing delete through *tombstone*
|
|
instead (`memory.el:46`). The invariant is a policy, not a property of the
|
|
accessor.
|
|
|