Nucleus Basalis Phase 1: ACh attention broadcaster (issue #116 follow-up)#122
Closed
TSchonleber wants to merge 2 commits into
Closed
Nucleus Basalis Phase 1: ACh attention broadcaster (issue #116 follow-up)#122TSchonleber wants to merge 2 commits into
TSchonleber wants to merge 2 commits into
Conversation
…-up) The basal-forebrain cholinergic broadcaster, target-locked attention complement to Locus Coeruleus's broad NE arousal broadcast. Pairs with the sibling LC PR (brain-regions-lc-phase-1). Together they codify the dual gain/attention control axes that the May 15 brain_region_coverage.md audit flagged as missing on the 🟡 partial list. LC fires on surprise (broadly, indiscriminately); NB fires on attention shifts (target-locked, narrow). NE widens the aperture; ACh sharpens the focus inside it. Both are necessary for the closed-loop architecture to balance exploration and exploitation correctly. Phase 1 is inspection-only / additive per the established phase pattern (Phase 1 schema → Phase 2 shadow → Phase 3 closed-loop → Phase 4 enforcement). No behavior change to retrieval, write gates, or any existing subsystem. - Migration 068 — 3 tables (nb_attention_targets, nb_firings, nb_state) + acetylcholine column on bg_modulators (the 4th neuromod dial; mirrors tonic_da, lc_ne, serotonin). 4 thalamic sectors seeded as targets. nb_state single-row seed. Idempotent; rollback DDL in header. - agentmemory.mcp_tools_nucleus_basalis — 5 MCP tools: - nb_status: current state + 24h firing summary + last 5 firings - nb_register_target: idempotent UPSERT on nb_attention_targets - nb_fire: record cholinergic broadcast; writes nb_firings + nb_state - nb_attend_sector: convenience wrapper resolving sector → target - nb_signal_history: paginated firing log with filters - 10 tests covering migration seeds, empty-state defaults, idempotent target registration, fire round-trip + state update, sector wrapper resolution, validation errors, and history filtering/pagination. - Design proposal at docs/proposals/nucleus_basalis.md with 4 biological invariants, architectural placement diagram, Phase 2/3/4 sketch. - brain_region_coverage.md updated: NB row gains "Phase 1 shipped" footnote. Phase 2 (separate PR) wires NB into the shadow consult at mcp_server.py:3265 to fire on thalamic_salience activations above threshold and broadcast ACh delta. Phase 3 closes the loop. Phase 4 enforces. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 20, 2026
CI schema_parity test was failing because the NB branch's init_schema.sql lacked the 066 (retrieval_pathway_log) and 068 (NB) table definitions, plus the bg_modulators.acetylcholine column added by 068. Fresh installs (init_schema only) drifted from upgraded installs (init_schema + all migrations). Mirrors the same backfill pattern the parallel LC branch used for 066/067. Closing-paren placement of the acetylcholine column matches SQLite's ALTER TABLE ADD COLUMN canonical form so the stored sqlite_master.sql is byte-identical between fresh and upgraded paths. Verified locally: tests/test_schema_parity.py + tests/test_mcp_tools_nucleus_basalis.py all green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Owner
Author
|
Superseded by #138 ( |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 1 of the Nucleus Basalis subsystem — basal-forebrain cholinergic broadcaster, the target-locked attention complement to Locus Coeruleus's broad-arousal NE broadcast. Pairs with the sibling LC PR (
brain-regions-lc-phase-1); together they codify the dual gain/attention control axes the May 15brain_region_coverage.mdaudit flagged as missing.Phase 1 ships schema + 5 read+CRUD MCP tools + tests + docs. No behavior change to retrieval, write gates, or any existing subsystem. Phase 2 wires the shadow consult; Phase 3 closes the loop; Phase 4 enforces — all separate PRs.
Context
NB and LC together complete the four-dial neuromod surface on
bg_modulators:tonic_da— BG actor exploration knob (shipped 054)lc_ne— LC norepinephrine broadcast (shipped 054, LC subsystem in sibling PR)serotonin— raphe-analog time-horizon dial (shipped 054)acetylcholine— added by this PR (the 4th dial)LC fires on surprise broadly; NB fires on attention shifts target-locked. NE widens the aperture; ACh sharpens the focus inside it. Both are necessary for the closed-loop architecture to balance exploration and exploitation correctly.
What's in
nb_attention_targets,nb_firings,nb_state) +acetylcholine REAL DEFAULT 0.5column onbg_modulators. 4 thalamic sectors seeded as targets (cognitive, episodic, semantic, pii_sensitive).nb_statesingle-row seed.agentmemory.mcp_tools_nucleus_basalis— 5 MCP tools (status / register_target / fire / attend_sector / signal_history).docs/proposals/nucleus_basalis.md— design doc with 4 biological invariants, architectural placement diagram, Phase 2/3/4 sketch.tests/test_mcp_tools_nucleus_basalis.py— 10 tests covering migration seeds, empty-state defaults, idempotent registration, fire round-trip + state updates, sector-wrapper resolution, validation errors, and history filtering/pagination.[Unreleased].docs/proposals/brain_region_coverage.md— NB row gains a "Phase 1 shipped" footnote.What's NOT in (deliberately)
mcp_server.py:3265. That's Phase 2 — different PR, daytime work.bg_modulators.acetylcholinewrites fromnb_fire. That's Phase 2.Live smoke
~/agentmemory/db/brain.db(backup at~/agentmemory/backups/brain.db.pre-nb-20260520T033433Z.db)bg_modulators.acetylcholine= 0.5 default present alongside the existing 3 dialsTest plan
docs/proposals/nucleus_basalis.mdpython3 -m pytest tests/test_mcp_tools_nucleus_basalis.py -x— should be 10/10 greenmcp_tools/list— confirm all discoverablebrain-regions-lc-phase-1) — they're meant to ship togetherParallel work
Sibling PR — Locus Coeruleus Phase 1 on branch
brain-regions-lc-phase-1(codex-authored under orchestration). Both should be reviewed together; LC + NB are the dual gain/attention control axes and the design assumes both ship.🤖 Generated with Claude Code