ZAM: deterministic context governance for AI agents

#ai #opensource #typescript #mcp

============================================================

dev.to post — copy each part into the matching field

--- TITLE (paste into the "Title" field) ---

--- TAGS (paste into the "Tags" field) ---

ai, llm, opensource, typescript

============================================================

BODY — copy EVERYTHING below this line into the post body

Most AI agents shove everything into the prompt every turn — every skill, every tool definition, every memory lane — no matter what the user actually asked. That bloats the prompt (cost + latency), buries the relevant context, and quietly degrades answers. Trimming by hand is risky: drop the wrong thing and you silently break safety or correctness.

I built ZAM — an open-source context governance layer — to make that decision deterministically.

What it does

ZAM runs before the prompt is assembled. Given the request and an inventory of available components (scaffolds, skills, tools, memory, history), a deterministic pipeline — request router -> 12-step selector ladder -> conflict resolver -> budgeter — decides which to include / omit / defer, and emits a structured plan plus a full decision trace. It never assembles prompt text itself: the model proposes, deterministic guardrails enforce.

The spine is fail-open on uncertainty: it only makes the context smaller when that's safe; when in doubt, it includes more. It's reproducible (no model call needed to plan), schema-validated, and fully auditable.

Evidence, not assertion

npm run benchmark   # offline, deterministic, no API key

63.9% mean token savings, 0 unsafe omissions vs. the inject-everything baseline.
A live tier shows the cheap deterministic router agrees with a model's classification 85.7% of the time — and both disagreements were on the safe side.

Portable: one core, three surfaces

The same core governs three very different surfaces with zero core changes:

an agent workspace (Markdown files),
MCP tools / resources / prompts — directly the "too many MCP servers blow my context window" problem,
a Telegram bot's per-message context.

(They're reference adapters over documented/synthetic inputs — the logic is real and reusable; the bundled examples are synthetic, stated in each.)

Try it

npm install context-plane

import { plan } from 'context-plane';
const { promptPlan } = plan({ request: { text: 'Help me debug the failing build.' }, registry });
console.log(promptPlan.selectedComponents); // include / omit / defer, each with a reason