el/tools/api-reshape/README.md

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).