bigmerge
f19040e484
Collapse ~90 noun-CRUD MCP tools into read/write/relate/supersede (type is a parameter) plus the live agentic primitives (think/attend/learn/ground/assert) already in the engram cognition build. Additive: old noun-tools aliased to the new ops. Vantage-read applies aperture -> a bounded slice, fixing the whole-self dumps. Signatures grounded in the live cognition binary; validated on an isolated nsbx clone (parity.sh: 12 proven, 0 failed). Live :8742 untouched.
78 lines
5.4 KiB
Markdown
78 lines
5.4 KiB
Markdown
# 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).
|