Workspace Bandwidth Limit Phase 1 (top-K-per-epoch enforcement)

CHANGELOG.md

@@ -5,6 +5,35 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
 
 ## [Unreleased]
 
+### Added — Workspace Bandwidth Limit Phase 1 (top-K-per-epoch)
+
+Closes the second half of the May 15 audit's workspace partial entry.
+Thalamus mode-broadcast closed the first half (org_state coupling);
+this closes the bandwidth-limit half. Biology: Dehaene-Changeux global
+neuronal workspace has a hard ~4-chunk ignition bandwidth.
+
+- **Migration 072** — 2 tables (`workspace_bandwidth_state` single
+  row + `workspace_bandwidth_epochs` history). Defaults: limit=4,
+  epoch_duration=60s, enforcement_mode='shadow'.
+- **`agentmemory.mcp_tools_workspace_bandwidth`** — 4 MCP tools:
+  `workspace_bandwidth_status`, `workspace_bandwidth_set`,
+  `workspace_bandwidth_admit`, `workspace_bandwidth_epochs_history`.
+- **Shadow / enforce / disabled modes.** In shadow, all admits go
+  through and `saturated=True` is informational. In enforce, admits
+  past the limit are rejected with `rejected=True`. In disabled,
+  behaves like shadow.
+- **Auto-rotation.** `workspace_bandwidth_status` and `_admit` both
+  check epoch expiry and roll the live counters into the historical
+  table.
+- **9 tests** covering defaults, status, admit-increment, saturation
+  detection, enforce-mode rejection, set validation, rotation,
+  history filters.
+
+Phase 2 wires `workspace_bandwidth_admit` into `workspace_ingest` so
+every real broadcast goes through the limit. Phase 3 lets ARAS
+mode-modulate the bandwidth (high arousal → wider; consolidation →
+narrower). Phase 4 enforces.
+
 ### Added — issue #116 Phase 1-A: retrieval pathway log
 
 External architecture memo (issue #116, "Thalamus, Basal Ganglia, and

db/migrations/072_workspace_bandwidth.sql

@@ -0,0 +1,63 @@
+-- Migration 072: workspace bandwidth limit — Phase 1 schema
+--
+-- The May 15 brain_region_coverage.md audit flagged the workspace
+-- (global neuronal workspace) as partial: "Fixed salience threshold,
+-- no org_state coupling, no enforced bandwidth limit (any module can
+-- write)."
+--
+-- The thalamus mode-broadcast layer (shipped via thalamus Phase 2)
+-- closed the org_state coupling half. This migration closes the
+-- remaining half: a top-K-per-epoch bandwidth limit on workspace
+-- broadcasts.
+--
+-- Biology: the global neuronal workspace (Dehaene-Changeux model) has
+-- a hard bandwidth — only ~4 chunks can be "ignited" at a time. Without
+-- that constraint, the workspace degenerates into a firehose. brainctl's
+-- current workspace_broadcasts table has no such limit; any module can
+-- write any time. Phase 1 adds the *bookkeeping*; Phase 2 enforces.
+--
+-- Schema:
+--   workspace_bandwidth_state — single row, current epoch + count
+--   workspace_bandwidth_epochs — historical log of completed epochs
+--
+-- Phase 1 is inspection-only / additive. Phase 2 wires the limit
+-- into workspace_ingest. Phase 3 lets the limit be context-modulated
+-- (high arousal = wider bandwidth; consolidation = narrower).
+--
+-- Rollback:
+--   DROP TABLE IF EXISTS workspace_bandwidth_epochs;
+--   DROP TABLE IF EXISTS workspace_bandwidth_state;
+--   DELETE FROM schema_version WHERE version = 72;
+--
+-- IDEMPOTENT.
+
+CREATE TABLE IF NOT EXISTS workspace_bandwidth_state (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    epoch_started_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%S', 'now')),
+    epoch_duration_seconds INTEGER NOT NULL DEFAULT 60 CHECK(epoch_duration_seconds > 0),
+    epoch_count INTEGER NOT NULL DEFAULT 0,        -- broadcasts in the current epoch
+    bandwidth_limit INTEGER NOT NULL DEFAULT 4 CHECK(bandwidth_limit > 0),
+    total_admits INTEGER NOT NULL DEFAULT 0,
+    total_rejects INTEGER NOT NULL DEFAULT 0,
+    enforcement_mode TEXT NOT NULL DEFAULT 'shadow' CHECK(enforcement_mode IN ('shadow', 'enforce', 'disabled')),
+    updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%S', 'now'))
+);
+INSERT OR IGNORE INTO workspace_bandwidth_state (id) VALUES (1);
+
+CREATE TABLE IF NOT EXISTS workspace_bandwidth_epochs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    epoch_started_at TEXT NOT NULL,
+    epoch_ended_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%S', 'now')),
+    duration_seconds INTEGER NOT NULL,
+    admitted_count INTEGER NOT NULL DEFAULT 0,
+    rejected_count INTEGER NOT NULL DEFAULT 0,
+    bandwidth_limit INTEGER NOT NULL,
+    enforcement_mode TEXT NOT NULL,
+    saturation REAL NOT NULL DEFAULT 0.0           -- admitted_count / bandwidth_limit
+);
+CREATE INDEX IF NOT EXISTS idx_wbe_recent ON workspace_bandwidth_epochs(epoch_ended_at);
+CREATE INDEX IF NOT EXISTS idx_wbe_saturated ON workspace_bandwidth_epochs(saturation);
+
+INSERT OR IGNORE INTO schema_version (version, description, applied_at)
+VALUES (72, 'workspace bandwidth Phase 1: 2 tables (state + epochs) for top-K-per-epoch limit',
+        strftime('%Y-%m-%dT%H:%M:%S', 'now'));

src/agentmemory/mcp_server.py

@@ -78,6 +78,7 @@
         mcp_tools_trust,
         mcp_tools_usage,
         mcp_tools_workspace,
+        mcp_tools_workspace_bandwidth,
         mcp_tools_world,
     )
     _EXT_MODULES = [
@@ -121,6 +122,7 @@
         mcp_tools_trust,
         mcp_tools_usage,
         mcp_tools_workspace,
+        mcp_tools_workspace_bandwidth,
         mcp_tools_world,
     ]
 except ImportError as _e: