# Neuron API-surface reshape

Design: artifact **0e828907** + design-brief **2b8078cf §5**. Collapse ~90
functional-CRUD MCP tools into a handful of **geometry ops** over the one
geometry, plus the **live agentic primitives** already in the engram cognition
build. **Type is a parameter, not a tool-per-noun.**

Ground-truth: routes verified against the live cognition binary
`engram.cognition-20260814-160045` (route source: branch
`feat/cognitive-architecture`, `engram/src/server.el`). Built + validated on an
**isolated nsbx clone** (`:8900`); live `:8742` untouched.

## Layer 1 — geometry ops

| op | signature | engram route | replaces (~) |
|----|-----------|--------------|--------------|
| `read` (vantage-read) | `read({vantage, type?, aperture:{k,depth}})` | GET `/api/search` \| `/api/neighbors/<id>` \| `/api/nodes/<id>` \| `/api/activate` | inspectGraph, searchGraph, traverseGraph, searchKnowledge, browseKnowledge, retrieveKnowledge, inspectMemories, searchEntities, recall, compileCtx, getSelfModel, reviewBacklog, findArtifacts, browseProcesses, listWork, inspectConfig … (~30) |
| `write` | `write({content, type, tags, importance})` | POST `/api/nodes` | remember, captureKnowledge, draftArtifact, planWork, defineProcess, addWonderQuestion, logInternalStateEvent … (~15) |
| `relate` | `relate({from, to, relationship, weight?})` | POST `/api/edges` | linkEntities, linkCausal, restructureCausalGraph, pin |
| `supersede` | `supersede({id, action: evolve\|supersede\|tombstone\|promote, content?})` | write+relate(`supersedes`) / DELETE `/api/nodes/<id>` (immutable marker) | evolveMemory, evolveKnowledge, forget→tombstone, promoteKnowledge, reviseArtifact, trackWork, progressWork(update) … (~15) |

**Vantage-read = the whole-self-dump fix.** Re-origin at a point + salience +
recency + **aperture** → a *bounded* slice. Aperture (`k`/`depth`) caps output:
measured on the clone, `limit=3 → 15 KB` vs `limit=50 → 363 KB`. The old path
returned 60k–230k-char unbounded traversals (this very session hit 104 KB and
409 KB live).

## Layer 2 — primitive agentic tools (Neuron runs itself)

The base verbs all agentic behavior composes from — grounded in the LIVE
cog-arch (`think` is the one operation; faculties are its steering-space labels;
the correspondence-beat is the reflexive learning loop).

| op | signature | engram route | status on clone |
|----|-----------|--------------|-----------------|
| `think` | `think({seeds, faculty})` faculty ∈ reason·abduce·induce·plan·analogize·recognize·discern·synthesize | GET `/api/think` | route wired; geometry-gated on HTTP daemon clone (validated via C harness: held-Brier 0.0286→0.0006 @ 10,994 nodes) |
| `attend` | `attend({node, observer, salience})` | POST `/api/attend` | **live** (returns `salient-to`) |
| `assert` | `assert({claim, for_whom, floor})` — realize, honesty-floored | GET `/api/assert` | **live** |
| `ground` | `ground({claim, evidence, for_whom})` | POST `/api/ground` | route wired; geometry-gated |
| `learn` | `learn({seeds, faculty, keystone})` — the correspondence-beat | POST `/api/correspondence-beat` | route wired; geometry-gated |

`comprehend`/`realize`/`intend` are **compositions**, not separate live
primitives: comprehend = write+activate (world→geometry), realize = assert
pointed at the world (geometry→act), intend = attend at a goal-region. The
skill-learning loop (decompose→detect-gap→reach-out-on-sparsity→verify-by-
execution→integrate) composes over `think`+`ground`+`learn`+`write`/`relate`.

## Identity is write-protected

`write(type=self|values)`, and `relate`/`supersede` touching the keystones
`kn-efeb4a5b…` / `kn-5b606390…`, are refused — identity routes through
intentional-cultivation, as enforced today.

## How the caller invokes Neuron agentically

Once the ops are registered as MCP tools (aliases in `surface.el`), the caller
(Claude, this loop) calls e.g.:

```
neuron.think({ seeds: "kn-efeb4a5b…", faculty: "plan" })   # Neuron reasons over its own geometry
neuron.attend({ node: <region> })                           # aim its attention
neuron.learn({ seeds: <region>, faculty: "induce" })        # calibrate its own prior (correspondence-beat)
neuron.read({ vantage: "self", aperture:{k:12} })           # bounded self-slice (no dump)
```

and **Neuron does the agentic work over its own geometry** — the beginning of it
running itself.

## Files
- `surface.el` — the reshaped surface (ops + agentic primitives + old-tool aliases), engram-HTTP idiom matching `neuron/mcp-wrapper/src/main.el`.
- `parity.sh` — proves it against the clone (`source ../../.nsbx-env && ./parity.sh`). Last run: **12 proven, 0 failed, 14 wired-but-gated/exec-skipped**.

## Honest ledger (built vs stubbed)
- **Proven live on clone:** read (3 forms), attend, assert, aperture-boundedness, parity spines.
- **Route-wired, geometry-gated on the HTTP daemon clone:** think (8 faculties), ground, learn. (The centered geometry isn't primed by the daemon boot on a clone — same on the peer clone `:8901`; the operation is exercised via the C cog-arch harness per `nsbx validate`.)
- **Route-wired, exec-skipped on clone:** write, relate, supersede — the paged-store node-write crashes a WAL-less cold-boot clone; run on a write-healthy store.
- **Not done:** compiling `surface.el` into the MCP server + hot-swap; wiring all ~90 aliases into `dispatch_tool_call`; the engram-side fix so a daemon clone primes geometry + survives writes. No promote to live (per rails).