Colony adaptive MCP overhead reduction with selective workflow guidance

What they did

On the Colony repo, the author opened a draft child PR (feat/adaptive-context-low-overhead) targeting the parent adaptive-context-budgets branch, with no merge or auto-merge authorized. The change makes the opt-in adaptive MCP path leaner: routine writable workflows expose only ask/push, read-only workflows expose only ask, and explicit memory management stays available through existing CLI commands or a full non-adaptive connection. Validated adaptive responses compact redundant source metadata but retain a top-level sources list of ref/content_hash pairs so downstream consumers (notably the merged PR16 evaluator) can bind findings to publications; sources with meaningful selectors, non-file kinds, unknown metadata, or incomplete identity coverage keep full metadata. The final canonical payload is recounted with its receipt, and evidence that cannot fit returns a safe budget-limited miss. A small-bundle correction preserves all required files for explicit whole-file requests on saved findings with no globally preselected passages, at most four files and <=2,800 combined source characters. Adaptive guidance was rewritten to allow cheap known-file reads to bypass memory while directing substantive multistep research through it, as best-effort guidance rather than enforced routing. The author added a regression that publishes a sourced trail via CLI/HTTP/Store, retrieves it through authenticated read-only MCP, and verifies trail ID, source identities, current text and the final budget receipt; it failed on the prior head with KeyError: sources. A pinned evaluator overlay added MCP research contracts, fact-scoped oracles, source-bound blank handling, protocol/collector guards and offline integration controls, applied as a hash-bound patch to merged PR16 Git blobs. Validation included the full suite (1018 passes, 36 platform skips), 26 scoped passes, 161 patched evaluator passes, Ruff, fresh wheel/install/CLI/HTTP/MCP demo, and all 27 installed runtime modules verified against Git. Native evaluation ran 28 matched sessions per arm at head e073919.

How it went

Tests, lint and scope/compatibility checks pass, and the source-map repair is validated by real source-bound narrow hits. The token evidence review failed: 28 fresh matched sessions at e073919 used 903,094 gross tokens without Colony versus 962,593 with Colony (+6.59%), reversing an earlier -4.04% at df9ba5c; uncached-input-plus-output was 111,542 versus 142,497 (+27.75%). Quality was close (Colony 13/14 correctness/grounding, 13/14 format; baseline 12/14 and 14/14), but required controlled publication/reuse coverage failed. No supported product win; the PR remains experimental and draft.

Worth knowing

No new model evaluations ran for the latest correction, so token evidence for the changed runtime and collector is pending; earlier e073919 and df9ba5c numbers are immutable and not inherited as current-head savings. The reversal cannot be attributed to the P2 fix because native client binary, agent/cache behavior and older checkpoint continuations differ. The unchanged checker has conservative blank-line coverage limits. Native Linux/macOS remain unverified, and 36 skips are environment limitations (Windows 8.3 aliases, symlink privileges). Offline token counts are representation counts, not measured provider prompts.

Wiring

Work happens on branch feat/adaptive-context-low-overhead, a draft child of PR #14 (feat/adaptive-context-budgets) based on 4ba3269, with no merge or auto-merge. Core edits are confined to src/colony/mcp.py plus two test files and the adaptive behavior documentation; dependency, ranking, storage and authorization implementations are untouched. The adaptive path is opt-in and installed as a single connection by routine setup; non-adaptive tools, schemas, instructions and payload bytes must match the pinned parent across unbound, writable and read-only profiles. The evaluator overlay is pinned and applied as a reviewed hash-bound patch to merged PR16 Git blobs on D:, with the framework and unrelated main-branch changes deliberately not imported. Validation order: targeted adaptive/context-budget/setup tests, then full suite, Ruff and whitespace, wheel/source archive build with all 27 runtime modules hash-verified against Git, fresh install, and a CLI/HTTP/Git/stdio-MCP demo covering source changes, branch mismatch, minimum-budget misses, writable tool exposure, management CLI access and server teardown. Native studies use matched sessions per arm with the same tasks, model, effort and budgets, and raw logs, costs, labels and continuation disclosures are retained.

Try it yourself

In this repo, reduce adaptive MCP overhead without changing non-adaptive behavior. Steps: (1) make routine writable adaptive workflows expose only ask/push and read-only workflows expose only ask, keeping explicit memory management available via existing CLI commands or a full non-adaptive connection; (2) compact redundant source metadata in validated adaptive responses but always retain a top-level sources list of ref/content_hash pairs, keeping full metadata when selectors are meaningful, kinds are non-file, metadata is unknown, or identity coverage is incomplete/conflicting; (3) recount the final canonical payload with its receipt and return a safe budget-limited miss when required evidence cannot fit; (4) fix small saved-source bundles so an explicit whole-file request preserves all required files when there are no globally preselected passages, at most four files and <=2,800 combined source characters; (5) rewrite adaptive guidance so cheap known-file reads bypass memory while substantive multistep research uses it, as best-effort guidance only; (6) add a regression that publishes a sourced trail through CLI/HTTP/Store, retrieves it via authenticated read-only MCP, and asserts trail ID, source identities, current text and the final budget receipt. Run the full suite, Ruff, a fresh wheel install and the CLI/HTTP/MCP demo, and report representation-level token counts separately from any native measurement.